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Develop your applications quickly and easily with the 
world's most intuitive mikroC PRO for PIC Microcontrollers. 

Highly sophisticated IDE provides the power you need with 
the simplicity of a Windows based point-and-click 
environment. 

With useful implemented tools, many practical code 
examples, broad set of built-in routines, and a 
comprehensive Help, mikroC PRO for PIC makes a fast 
and reliable tool, which can satisfy needs of experienced 
engineers and beginners alike. 
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Reader's note 



DISCLAIMER: 

mikroC PRO for PIC and this manual are owned by mikroElektronika and are protected 
by copyright law and international copyright treaty. Therefore, you should treat this manual 
like any other copyrighted material (e.g., a book). The manual and the compiler may not be 
copied, partially or as a whole without the written consent from the mikroEelktronika. The 
PDF-edition of the manual can be printed for private or local use, but not for distribution. 
Modifying the manual or the compiler is strictly prohibited. 



HIGH RISK ACTIVITIES: 

The mikroC PRO for PIC compiler is not fault-tolerant and is not designed, manufactured 
or intended for use or resale as on-line control equipment in hazardous environments requir- 
ing fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or 
communication systems, air traffic control, direct life support machines, or weapons systems, 
in which the failure of the Software could lead directly to death, personal injury, or severe 
physical or environmental damage ("High Risk Activities"). mikroElektronika and its suppliers 
specifically disclaim any express or implied warranty of fitness for High Risk Activities. 

LICENSE AGREEMENT: 

By using the mikroC PRO for PIC compiler, you agree to the terms of this agreement. 
Only one person may use licensed version of mikroC PRO for PIC compiler at a time. 
Copyright © mikroElektronika 2003 - 2009. 

This manual covers mikroC PRO for PIC version 1.1 and the related topics. Newer ver- 
sions may contain changes without prior notice. 

COMPILER BUG REPORTS: 

The compiler has been carefully tested and debugged. It is, however, not possible to 
guarantee a 100 % error free product. If you would like to report a bug, please contact us at 
the address office@mikroe.com. Please include next information in your bug report: 

- Your operating system 

- Version of mikroC PRO for PIC 

- Code sample 

- Description of a bug 

CONTACT US: 

mikroElektronika 

Voice: +381(11)36 28 830 

Fax: +381(11)36 28 831 

Web: www.mikroe.com 

E-mail: office@mikroe.com 



Windows is a Registered trademark of Microsoft Corp. All other trade and/or services marks 
are the property of the respective owners. 
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Introduction to 
mikroC PRO for PIC 



The mikroC PRO for PIC is a powerful, feature-rich development tool for PIC 
microcontrollers. It is designed to provide the programmer with the easiest possi- 
ble solution to developing applications for embedded systems, without compromis- 
ing performance or control. 
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mikroC PRO for PIC IDE 

PIC and C fit together well: PIC is the most popular 8-bit chip in the world, used in 
a wide variety of applications, and C, prized for its efficiency, is the natural choice 
for developing embedded systems. mikroC PRO for PIC provides a successful 
match featuring highly advanced IDE, ANSI compliant compiler, broad set of hard- 
ware libraries, comprehensive documentation, and plenty of ready-to-run examples. 

Features 



mikroC PRO for PIC allows you to quickly develop and deploy complex applications: 

■ Write your C source code using the built-in Code Editor (Code and Parameter 
Assistants, Code Folding, Syntax Highlighting, Auto Correct, Code Templates, 
and more.) 

■ Use included mikroC PRO for PIC libraries to dramatically speed up the devel 
opment: data acquisition, memory, displays, conversions, communication etc. 

■ Monitor your program structure, variables, and functions in the Code Explorer. 

■ Generate commented, human-readable assembly, and standard HEX compati 
ble with all programmers. 

■ Use the integrated mikrolCD (In-Circuit Debugger) Real-Time debugging tool to 
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monitor program execution on the hardware level. 

■ Inspect program flow and debug executable logic with the integrated Software 
Simulator. 

■ Get detailed reports and graphs: RAM and ROM map, code statistics, assembly 
listing, calling tree, and more. 

■ mikroC PRO for PIC provides plenty of examples to expand, develop, and use 
as building bricks in your projects. Copy them entirely if you deem fit - that's why 
we included them with the compiler. 

Where to Start 

■ In case that you're a beginner in programming PIC microcontrollers, read care 
fully the PIC Specifics chapter. It might give you some useful pointers on PIC 
constraints, code portability, and good programming practices. 

■ If you are experienced in C programming, you will probably want to consult 
mikroC PRO for PIC Specifics first. For language issues, you can always refer to 
the comprehensive Language Reference. A complete list of included libraries is 
available at mikroC PRO for PIC Libraries. 

■ If you are not very experienced in C programming, don't panic! mikroC PRO for 
PIC provides plenty of examples making it easy for you to go quickly. We sug 
gest that you first consult Projects and Source Files, and then start browsing the 
examples that you're the most interested in. 
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MIKROELEKTRONIKA ASSOCIATES LICENSE STATEMENT AND 
LIMITED WARRANTY 

IMPORTANT - READ CAREFULLY 

This license statement and limited warranty constitute a legal agreement ("License 
Agreement") between you (either as an individual or a single entity) and mikroElek- 
tronika ("mikroElektronika Associates") for software product ("Software") identified 
above, including any software, media, and accompanying on-line or printed docu- 
mentation. 

BY INSTALLING, COPYING, OR OTHERWISE USING SOFTWARE, YOU AGREE 
TO BE BOUND BY ALL TERMS AND CONDITIONS OF THE LICENSE 
AGREEMENT. 

Upon your acceptance of the terms and conditions of the License Agreement, 
mikroElektronika Associates grants you the right to use Software in a way provided 
below. 

This Software is owned by mikroElektronika Associates and is protected by copy- 
right law and international copyright treaty. Therefore, you must treat this Software 
like any other copyright material (e.g., a book). 

You may transfer Software and documentation on a permanent basis provided. You 
retain no copies and the recipient agrees to the terms of the License Agreement. 
Except as provided in the License Agreement, you may not transfer, rent, lease, 
lend, copy, modify, translate, sublicense, time-share or electronically transmit or 
receive Software, media or documentation. You acknowledge that Software in the 
source code form remains a confidential trade secret of mikroElektronika Associates 
and therefore you agree not to modify Software or attempt to reverse engineer, 
decompile, or disassemble it, except and only to the extent that such activity is 
expressly permitted by applicable law notwithstanding this limitation. 

If you have purchased an upgrade version of Software, it constitutes a single prod- 
uct with the mikroElektronika Associates software that you upgraded. You may use 
the upgrade version of Software only in accordance with the License Agreement. 
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LIMITED WARRANTY 

Respectfully excepting the Redistributables, which are provided "as is", without war- 
ranty of any kind, mikroElektronika Associates warrants that Software, once updat- 
ed and properly used, will perform substantially in accordance with the accompany- 
ing documentation, and Software media will be free from defects in materials and 
workmanship, for a period of ninety (90) days from the date of receipt. Any implied 
warranties on Software are limited to ninety (90) days. 

mikroElektronika Associates' and its suppliers' entire liability and your exclusive 
remedy shall be, at mikroElektronika Associates' option, either (a) return of the price 
paid, or (b) repair or replacement of Software that does not meet mikroElektronika 
Associates' Limited Warranty and which is returned to mikroElektronika Associates 
with a copy of your receipt. DO NOT RETURN ANY PRODUCT UNTIL YOU HAVE 
CALLED MIKROELEKTRONIKAASSOCIATES FIRST AND OBTAINED A RETURN 
AUTHORIZATION NUMBER. This Limited Warranty is void if failure of Software has 
resulted from an accident, abuse, or misapplication. Any replacement of Software 
will be warranted for the rest of the original warranty period or thirty (30) days, 
whichever is longer. 

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, 
MIKROELEKTRONIKA ASSOCIATES AND ITS SUPPLIERS DISCLAIM ALL 
OTHER WARRANTIES AND CONDITIONS, EITHER EXPRESSED OR IMPLIED, 
INCLUDED, BUT NOT LIMITED TO IMPLIED WARRANTIES OF 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND 
NON-INFRINGEMENT, WITH REGARD TO SOFTWARE, AND THE PROVISION 
OF OR FAILURE TO PROVIDE SUPPORT SERVICES. 

IN NO EVENT SHALL MIKROELEKTRONIKAASSOCIATES OR ITS SUPPLIERS 
BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL 
DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES 
FOR LOSS OF BUSINESS PROFITS AND BUSINESS INFORMATION, BUSINESS 
INTERRUPTION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE 
USE OF OR INABILITY TO USE SOFTWARE PRODUCT OR THE PROVISION OF 
OR FAILURE TO PROVIDE SUPPORT SERVICES, EVEN IF 
MIKROELEKTRONIKAASSOCIATES HAS BEEN ADVISED OF THE POSSIBILITY 
OF SUCH DAMAGES. IN ANY CASE, MIKROELEKTRONIKA ASSOCIATES' 
ENTIRE LIABILITY UNDER ANY PROVISION OF THIS LICENSE AGREEMENT 
SHALL BE LIMITED TO THE AMOUNT ACTUALLY PAID BY YOU FOR 
SOFTWARE PRODUCT PROVIDED, HOWEVER, IF YOU HAVE ENTERED INTO 
A MIKROELEKTRONIKA ASSOCIATES SUPPORT SERVICES AGREEMENT, 
MIKROELEKTRONIKA ASSOCIATES' ENTIRE LIABILITY REGARDING 
SUPPORT SERVICES SHALL BE GOVERNED BY THE TERMS OF THAT 
AGREEMENT. 
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HIGH RISK ACTIVITIES 

Software is not fault-tolerant and is not designed, manufactured or intended for use 
or resale as on-line control equipment in hazardous environments requiring fail-safe 
performance, such as in the operation of nuclear facilities, aircraft navigation or 
communication systems, air traffic control, direct life support machines, or weapons 
systems, in which the failure of Software could lead directly to death, personal injury, 
or severe physical or environmental damage ("High Risk Activities"). mikroElektron- 
ika Associates and its suppliers specifically disclaim any expressed or implied war- 
ranty of fitness for High Risk Activities. 

GENERAL PROVISIONS 

This statement may only be modified in writing signed by you and an authorised offi- 
cer of mikroElektronika Associates. If any provision of this statement is found void 
or unenforceable, the remainder will remain valid and enforceable according to its 
terms. If any remedy provided is determined to have failed for its essential purpose, 
all limitations of liability and exclusions of damages set forth in the Limited Warran- 
ty shall remain in effect. 

This statement gives you specific legal rights; you may have others, which vary, from 
country to country. mikroElektronika Associates reserves all rights not specifically 
granted in this statement. 

mikroElektronika 

Visegradska 1A, 
11000 Belgrade, 
Europe. 

Phone: + 381 11 36 28 830 
Fax: +381 11 36 28 831 
Web: www.mikroe.com 
E-mail: office@mikroe.com 
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TECHNICAL SUPPORT 

In case you encounter any problem, you are welcome to our support forums at 
www.mikroe.com/forum/. Here, you may also find helpful information, hardware tips, 
and practical code snippets. Your comments and suggestions on future develop- 
ment of the mikroC PRO for PIC are always appreciated — feel free to drop a note 
or two on our Wishlist. 

In our Knowledge Base www.mikroe.com/en/kb/ you can find the answers to Fre- 
quently Asked Questions and solutions to known problems. If you can not find the 
solution to your problem in Knowledge Base then report it to Support Desk 
www.mikroe.com/en/support/. In this way, we can record and track down bugs more 
efficiently, which is in our mutual interest. We respond to every bug report and ques- 
tion in a suitable manner, ever improving our technical support. 
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HOW TO REGISTER 

The latest version of the mikroC PRO for PIC is always available for downloading 
from our website. It is a fully functional software libraries, examples, and compre- 
hensive help included. 

The only limitation of the free version is that it cannot generate hex output over 2 
KB. Although it might sound restrictive, this margin allows you to develop practical, 
working applications with no thinking of demo limit. If you intend to develop really 
complex projects in the mikroC PRO for PIC, then you should consider the possibil- 
ity of purchasing the license key. 

Who Gets the License Key 

Buyers of the mikroC PRO for PIC are entitled to the license key. After you have 
completed the payment procedure, you have an option of registering your mikroC 
PRO. In this way you can generate hex output without any limitations. 

How to Get License Key 

After you have completed the payment procedure, start the program. Select Help > How 
to Register from the drop-down menu or click the How To Register Icon ) . Fill out the 
registration form (figure below), select your distributor, and click the Send button. 
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H How To Register 

Step 1. Fill in the form below, Please., make sure you fill in all required fields, 

Step 2. Make sure that you provided a valid email address in the "EMAIL" edit box. This email will be used for 

sending you the activation key. 

Step 3. Make sure you select a correct distributor which will make the registration process faster. If your 

distributor is not on the list then select "Other" and type in distributor's email address in the box below, 

Step 4. Press the SEND button to send key request. A default email client will open with ready-to-send message. 

Note: If email client does not open, you may copy text of the message and paste it manually into a new email 

message before sending it to your distributor's email, 



NAME* 



Marko Jovanovic 



Enter your address 



Enter invoice number if available in the form AAAAA/BB 



Enter 2CheckOut Order Number if available (10 digits) 



E-MAIL* 



rmarko@mikroe.com 



E-MAIL* 



marko@mikroe.com 



Enter company name 



515C-557269-6F6D72-5751 



COMMENTS: Enter comments on your order 



DISTRIBUTOR* mikroElektronika 



I have made the payment and I wish to request activation key for mikroC PRO for PIC 



key@mikroe.com 



* Required fields 



Name: 

Marko Jovanovic 

Address: 

Invoice number: 
2CheckOut order number: 

Company: 



E-Mail: 

marko@mikroe.com 

Product key: 

515C-557269-6F6D72-5751 



i 



Copytc clipboard 



SEND 



Cancel 



This will start your e-mail client with message ready for sending. Review the infor- 
mation you have entered, and add the comment if you deem it necessary. Please, 
do not modify the subject line. 

Upon receiving and verifying your request, we will send the license key to the e-mail 
address you specified in the form. 
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After Receiving the License Key 

The license key comes as a small autoextracting file -just start it anywhere on your 
computer in order to activate your copy of compiler and remove the demo limit. You 
do not need to restart your computer or install any additional components. Also, 
there is no need to run the mikroC PRO for PIC at the time of activation. 

Notes: 

■ The license key is valid until you format your hard disk. In case you need to for 
mat the hard disk, you should request a new activation key. 

■ Please keep the activation program in a safe place. Every time you upgrade the 
compiler you should start this program again in order to reactivate the license. 
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mikroC PRO for PIC 
Environment 

The mikroC PRO for PIC is an user-friendly and intuitive environment. 
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IDE Overview 
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The Code Editor features adjustable Syntax Highlighting, Code Folding, Code 
Assistant, Parameters Assistant, Auto Correct for common typos and Code Tern 
plates (Auto Complete). 

The Code Explorer is at your disposal for easier project management. 
The Project Manager alows multiple project management 
General project settings can be made in the Project Settings window 
Library manager enables simple handling libraries being used in a project 
The Error Window displays all errors detected during compiling and linking. 
The source-level Software Simulator lets you debug executable logic step-by- 
step by watching the program flow. 

The New Project Wizard is a fast, reliable, and easy way to create a project. 
Help files are syntax and context sensitive. 

Like in any modern Windows application, you may customize the layout of 
mikroC PRO for PIC to suit your needs best. 

Spell checker underlines identifiers which are unknown to the project. In this way 
it helps the programmer to spot potential problems early, much before the proj 
ect is compiled. 

Spell checker can be disabled by choosing the option in the Preferences dialog 
(F12). 
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MAIN MENU OPTIONS 

Available Main Menu options are: 



File 








Edit 








View 






Project 






Run 








Tools 








Help 





Related topics: Keyboard shortcuts 
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FILE MENU OPTIONS 

The File menu is the main entry point for manipulation with the source files. 



_J 


New Unit Ctrl+N 


& 


Open Ctrl+O 




Recent Files ^ 


n 


5ave Ctrl+5 


m 


Save As... 




Close Ctrl+F4 


Print... Ctrl+P 


Exit Alt+X 



File 


Description 


Q New Unit Ctrl+N 


Open a new editor window. 


(2^ Open Ctrl+O 


Open source file for editing or image file for viewing. 


Recent Files ► 


Reopen recently used file. 


L~ J Save Ctrl+S 


Save changes for active editor. 




Save the active source file with the different name or 
change the file type. 


|f| Save As... 




H Close Alt+F4 


Close active source file. 


^ Print... Ctrl+P 


Print Preview. 


£ Exit Alt+X 


Exit IDE. 



Related topics: Keyboard shortcuts, File Toolbar, Managing Source Files 
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EDIT MENU OPTIONS 



<Ji 


Undo 


Ctrl+Z 




Redo Shift+Ctrl+Z 


Cut 


Ctrl+X 


£ 


Copy 


Ctrl+C 


m 


Paste 


Ctrl+V 


X 


Delete 




p 


Select All 


Ctrl+A 


Find,,, 


Ctrl+F 


k 


Find Next 


F3 


V 


Fjnd Previous 


5hift+F3 


p 


Replace... 


Ctrl+R 


@ 


Find In Fi[es... 


Alt+F3 


■'■ 


Goto Line... 


Ctrl+G 


Advanced 


► 



Edit 


Description 


<£l Undo 


Ctrl+Z 


Undo last change. 


Redo Shift+Ctrl+Z 


Redo last change. 


& C * 


Ctrl+X 


Cut selected text to clipboard. 


is] Copy 


Ctrl+C 


Copy selected text to clipboard. 


jj ^ aste 


Ctrl+V 


Paste text from clipboard. 


X Delete 


Delete selected text. 


Select All 


Ctrl+A 


Select all text in active editor. 


Find... 


Ctrl+F 


Find text in active editor. 


j^t, Find Next 


F3 


Find next occurence of text in active editor. 


jj> Find Previous 


5hift+F3 


Find previous occurence of text in active editor. 


Jtfi Replace... 


Ctrl+R 


Replace text in active editor. 




Find text in current file, in all opened files, or in 
from desired folder. 


files 


Q Find In Files... 


Alt+F3 




*_] Goto Line... 


Ctrl+G 


Goto to the desired line in active editor. 


Advanced 


► 


Advanced Code Editor options 
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Advanced » 


Description 




Comment selected code or put single line com- 
ment if there is no selection. 


{..} Comment 


Shift+Ctrl-l-. 






Uncomment selected code or remove single line 
comment if there is no selection. 


{..} Uncomment 


Shift+Ctrl+j 




*|* Indent 


Shift+Ctrl+I 


Indent selected code. 


J+ Outdent 


Shift+Ctrl+U 


Outdent selected code. 


AaJ Lowercase 


Ctrl+Alt+L 


Changes selected text case to lowercase. 


aAj Uppercase 


Ctrl+Alt+U 


Changes selected text case to uppercase. 


4^\ Titlecase 


Ctrl+Alt+T 


Changes selected text case to titlercase. 



Find Text 



Dialog box for searching the document for the specified text. The search is per- 
formed in the direction specified. If the string is not found a message is displayed. 



Find Text 
Search for: 



-Options — 

Case sensitivity 

Whole words only 

Search from caret 

Selected text only 

Regular expression 



rDirection — 
I Forward 



Backward 



OK 



Cancel 



16 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 2 
Environment 



Replace Text 

Dialog box for searching for a text string in file and replacing it with another text string. 

[^ Replace Ted: 



Search for: 
Replace with: 
-Options — 



rnikroElektronika 



rnikroE 



Case sensitivity 
Whole words only 
Search from caret 
Selected tent only 
Regular expression 



rDirection — 
a Forward 



Backward 



OK Cancel 



Find In Files 

Dialog box for searching for a text string in current file, all opened files, or in files on a disk. 

The string to search for is specified in the Text to find field. If Search in directories option 
is selected, The files to search are specified in the Files mask and Path fields. 



Grep search 



^ 



Text to find: BHiffldigSfflffHJfl 



-Options — 

Case sensitive 

Whole words 


-Where — 
_' Current file 

All opened files 
"*' Search in directories 



■Search directory options- 



Files mask: *.* 



Path: 




C:\Prograrm files\ 
Include subdirectories 



Cancel 
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Go To Line 

Dialog box that allows the user to specify the line number at which the cursor should 
be positioned. 



Go To Line 
Go To Line INuber 






OK 



Cancel 



Regular expressions option 

By checking this box, you will be able to advance your search, through Regular 
expressions. 



Find Text 
Search for: 



unsigned\x20int 



-Options — 

Case sensitivity 

Whole words only 

Search from caret 

Selected text only 

•f JReguJar expression 



rDirection — 
g Forward 



Backward 



OK 



Cancel 



Related topics: Keyboard shortcuts, Edit Toolbar, Advanced Edit Toolbar 
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VIEW MENU OPTIONS 



Toolbars 
Debug Windows 



Routine List Ctrl+L 

Project Settings 

Code Explorer 

Project Manager 5hift+Ctrl+Fl 1 

Library Manager 

Bookmarks 

Messages 

Macro Editor 



Windows 



File 


Description 


Toolbars 


Show/Hide toolbars. 


Debug Windows 


Show/Hide debug windows. 


} Routines List 


Show/Hide Routine List in active editor. 


Project Settings 


Show/Hide Project Settings window. 


1| Code Explorer 


Show/Hide Code Explorer window. 


Project Manager 5hift+Qrl4 


Show/Hide Project Manager window. 


Library Manager 


Show/Hide Library Manager window. 


Bookmarks 


Show/Hide Bookmarks window. 


Messages 


Show/Hide Error Messages window. 


Macro Editor 


Show/Hide Macro Editor window. 


Lq Windows 


Show Window List window. 
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TOOLBARS 
File Toolbar 



File Toolbar is a standard toolbar with following options: 



Icon 


Description 


i± 


Opens a new editor window. 


&- 


Open source file for editing or image file for viewing. 


u 


Save changes for active window. 


m 


Save changes in all opened windows. 


u 


Close current editor. 


D D 


Close all editors. 


& 


Print Preview. 



Edit Toolbar 



a 



Edit Toolbar is a standard toolbar with following options: 



Icon 


Description 


<a 


Undo last change. 


& 


Redo last change. 




Cut selected text to clipboard. 




Copy selected text to clipboard. 


(3 


Paste text from clipboard. 
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Advanced Edit Toolbar 



Advanced Edit Toolbar comes with following options: 



Icon 


Description 


{■■} 


Comment selected code or put single line comment if there is no selection 




Uncomment selected code or remove single line comment if there is 
no selection. 


{■■} 


J 


3g| 


Select text from starting delimiter to ending delimiter. 


EEC-I 
EMD| 


Go to ending delimiter. 


*J 


Go to line. 


J^I~1 


Indent selected code lines. 


■H 


Outdent selected code lines. 




Generate HTML code suitable for publishing current source code on 
the web. 


^ 



Find/Replace Toolbar 



Find/Replace Toolbar is a standard toolbar with following options: 



Icon 


Description 


P 


Find text in current editor. 


A 


Find next occurence. 


P 


Find previous occurence. 


M 


Replace text. 


1 


Find text in files. 
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Project Toolbar 



Project Toolbar comes with following options: 



Icon 


Description 


R_l 


New project 


m- 


Open Project 


H 


Save Project 


m 


Close current project. 


■ 


Edit project settings. 


e 


Add existing project to project group. 


e 


Remove existing project from project group. 


e? 


Add File To Project 


# 


Remove File From Project 



Build Toolbar 

% ^^ Uffl 
Build Toolbar comes with the following options: 



Icon 


Description 




Build current project. 


$> 


Build all opened projects. 


•\.\\i 


Build and program active project. 


$> 


Start programmer and load current HEX file. 


a 


Open assembly code in editor. 


a 


Open lisitng file in editor. 


na 


View statistics for current project. 
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Debugger 



Debugger Toolbar comes with following options: 



Icon 


Description 


& 


Start Software Simulator or mikrolCD (In-Circuit Debugger). 


Lew 


Run/Pause debugger. 


a 


Stop debugger. 


C-o 


Step into. 


*£] 


Step over. 


[10 


Step out. 


01 


Run to cursor. 


(il 


Toggle breakpoint. 


B 


Toggle breakpoints. 


% 


Clear breakpoints. 


&r 


View watch window 




View stopwatch window 



Styles Toolbar 



Office 2003 Blue 


WBtMMMrl 




Office 2003 Silver 




Office 2003 Olive 




Office XP 




Chocolate 




Arctic 


Silverfox 
Soft sand 



Styles toolbar allows you to easily customize your workspace. 
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Tools Toolbar 

5' J - L f 

Tools Toolbar comes with following default options: 



Icon 


Description 


"' 


Run US ART Terminal 




EEPROM 




ASCII Chart 


& 


Seven segment decoder tool. 


5* 


Options menu 



The Tools toolbar can easily be customized by adding new tools in Options (F12) 
window. 

Related topics: Keyboard shortcuts, Integrated Tools, Debugger Windows 
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PROJECT MENU OPTIONS 



% 


Build Ctrl+F9 


& 


Build All Projects 5hift+F9 


% 


Build + Program Ctrl+Fl 1 


m 


View Assembly 




Edit Search Paths... 




C[eanProjectFolder... 


Add File To Project... 


if 


Remove File From Project 


Import Pro ject .. , Ctrl+I 


New Pro ject . . . Shif t+Ctrl+N 


© 


Open Project... Shift+Ctrl+O 


^9 


Save Project 


- 


Edit Project... Shift+Ctrl+E 


& 


Open Project Group... 


^ 


Close Project Group 


19 


Save Project As... 


Recent Projects ► 


Close Project 
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Project 


Description 


% Build Ctrl+F9 


Build active project. 


j$t Build All Projects Shift+F9 


Build all projects. 


^P Build + Program Qrl+Fll 


Build and program active project. 


BJ| View Assembly 


View Assembly. 


Edit Search Paths... 


Edit search paths. 


.=, ,. Clean Project Folder. . . 


Clean Project Folder 


ffj Add File To Project... 


Add file to project. 


Remove File From Project 


Remove file from project. 


j|j Import Project... Ctrl+I 


Import projects from previous versions of mikroC. 


Q) New Project... 


Open New Project Wizard 


[^ Open Project... Shift+Ctrl+O 


Open existing project. 


|^ Save Project 


Save current project. 


[^ Edit Pro ject .. . Shif t+Ctrl+E 


Edit project settings 


g Op_en Project Group . . . 


Open project group. 


Close Project Group 


Close project group. 


|*2 Save Project As... 


Save active project file with the different name. 


Recent Projects ► 


Open recently used project. 


Close Project 


Close active project. 



Related topics: Keyboard shortcuts, Project Toolbar, Creating New Project, Project 
Manager, Project Settings 



26 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 2 
Environment 



RUN MENU OPTIONS 



a 


Start Debugger 


F9 


m 


Stop Debugger 


Ctrl+F2 


On 


Pause Debugger 


F6 


Step Into 


F7 


K. 


Step Over 


F8 


no 


Step Out 


Ctrl+F8 


S 


Jump To Interrupt 


F2 


Toggle Breakpoint 


F5 


n 


Breakpoints 


Shift+F4 


L L; , 


Clear Breakpoints 


Shift+Ctrl+F5 


Watch Window 


Shift+F5 


$ 


View Stopwatch 




Disassembly mode 


Alt+D 



Run 



Start Debugger 



F9 



Stop Debugger 



Ctrl+F2 



eJj Pause Debugger 



F6 



Qo Step Into 



F7 



*d Step Over 



F8 



t)4> Step Out 



Ctrl+F8 



^p< Jump To Interrupt 



F2 



Toggle Breakpoint 



F5 



Show/Hide Breakpoints Shift+F4 



^t Clear Breakpoints Shift+Ctrl+F5 



crcT Watch Window 



5hift+F5 



@ View Stopwatch 



Disassembly mode 



Ctrl+D 



Description 



Start Software Simulator or mikrolCD (In- 
Circuit Debugger). 



Stop debugger. 



Pause Debugger. 



Step Into. 



Step Over. 



Step Out. 



Jump to interrupt in current project. 



Toggle Breakpoint. 



Breakpoints. 



Clear Breakpoints. 



Show/Hide Watch Window 



Show/Hide Stopwatch Window 



Toggle between Pascal source and disas- 
sembly. 



Related topics: Keyboard shortcuts, Debug Toolbar 
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TOOLS MENU OPTIONS 



mE Programmer 



Fll 



USART Terminal Ctrl+T 

EEPROM Editor 

Ascii Chart 

Seven Segment Convertor 

Export Code To HTML 

LCD Custom Character 

GLCD Bitmap Editor 

HID Terminal 

UDP Terminal 

mikroEootloader 



Options 



F12 



Tools 


Description 


<*£> mE Programmer Fll 


Run mikroElektronika Programmer 


<■] USART Terminal Ctrl+T 


Run USART Terminal 


01 EEPROM Editor 


Run EEPROM Editor 


Ascii Chart 


Run ASCII Chart 


E^J Seven Segment Convertor 


Run 7 Segment Display Converter 




Generate HTML code suitable for publishing 
source code on the web. 


El Export Code To HTML 




LCD Custom Character 


Run Led custom character. 


i [\ GLCD Bitmap Editor 


Run Glcd bitmap editor. 


HID Terminal 


Run HID Terminal. 


UDP Terminal 


Run UDP communication terminal. 


mikroBootloader 


Run mikroBootloader. 


=jf Options F12 


Open Options window. 



Related topics: Keyboard shortcuts, Tools Toolbar 
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HELP MENU OPTIONS 



Help 

Migration Document 



Fl 



Check For Updates 
mikroElektronika Support Forums 
mikroElektronika Web Page 



How To Register 
About 



Help 


Description 


S fclelP F1 


Open Help File. 


Migration Document 


Open Code Migration Document. 


Check For Updates 


Check if new compiler version is available. 




Open mikroElektronika Support Forums in 
a default browser. 


mikroElektronika Support Forums 






Open mikroElektronika Web Page in a 
default browser. 


mikroElektronika Web Page 




How To Register 


Information on how to register 


About 


Open About window. 



Related topics: Keyboard shortcuts 
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KEYBOARD SHORTCUTS 

Below is a complete list of keyboard shortcuts available in mikroC PRO for PIC IDE. 



IDE Shortcuts 


F1 


Help 


Ctrl+N 


New Unit 


Ctrl+O 


Open 


Ctrl+Shift+O 


Open Project 


Ctrl+Shift+N 


New Project 


Ctrl+K 


Close Project 


Ctrl+F4 


Close Unit 


Ctr+Shift+E 


Edit Project 


Ctrl+F9 


Build 


Shift+F9 


Build All 


Ctrl+F11 


Build And Program 


Shift+F4 


View Breakpoints 


Ctrl+Shift+F5 


Clear Breakpoints 


F11 


Start mE Programmer 


Ctrl+Shift+F1 


Project Manager 


F12 


Options 


Alt+X 


Close mikroC PRO for PIC 


Basic Editor Shortcuts 


F3 


Find, Find Next 


Shift+F3 


Find Previous 


Alt+F3 


Grep Search, Find in Files 


Ctrl+A 


Select All 


Ctrl+C 


Copy 


Ctrl+F 


Find 


Ctrl+R 


Replace 


Ctrl+P 


Print 


Ctrl+S 


Save unit 



Ctrl+Shift+S 


Save All 


Ctrl+V 


Paste 


Ctrl+X 


Cut 


Ctrl+Y 


Delete entire line 


Ctrl+Z 


Undo 


Ctrl+Shift+Z 


Redo 


Advanced Editor Shortcuts 


Ctrl+Space 


Code Assistant 


Ctrl+Shift+Space 


Parameters Assistant 


Ctrl+D 


Find declaration 


Ctrl+E 


Incremental Search 


Ctrl+L 


Routine List 


Ctrl+G 


Goto line 


Ctrl+J 


Insert Code Template 


Ctrl+Shift+. 


Comment Code 


Ctrl+Shift+, 


Uncomment Code 


Ctrl+number 


Goto bookmark 


Ctrl+Shift+number 


Set bookmark 


Ctrl+Shift+I 


Indent selection 


Ctrl+Shift+U 


Unindent selection 


TAB 


Indent selection 


Shift+TAB 


Unindent selection 


Alt+Select 


Select columns 


Ctrl+Alt+Select 


Select columns 


Ctrl+Alt+L 


Convert selection to 
lowercase 


Ctrl+Alt+U 


Convert selection to 
uppercase 


Ctrl+Alt+T 


Convert to Titlecase 
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mikrolCD Debugger and Software 
Simulator Shortcuts 


F2 


Jump to Interrupt 


F4 


Run to Cursor 


F5 


Toggle Breakpoint 


F6 


Run/Pause Debugger 


F7 


Step into 


F8 


Step over 


F9 


Debug 


Ctrl+F2 


Stop Debugger 


Ctrl+F5 


Add to Watch List 


Ctrl+F8 


Step out 


Alt+D 


Dissasembly View 


Shift+F5 


Open Watch Window 


Ctrl+Shift+A 


Show Advanced Breakpoints 
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IDE OVERVIEW 

The mikroC PRO for PIC is an user-friendly and intuitive environment: 



LCC_M_Oimc«irv 
LCD_Dt_OiniH»ni 
ieC_BT_Oi™di.f» 
«D_EH_Kn.rtun 




* <w It 



a EeV*_P*l*tf)J I 



■:■->■. , 

,„,FO!_E.|Wfrl 



„,.,,,..; ,Ki,,.. 1. 1 «k_-itti ■:■■>!•* 



■■'::-'i'H: -=J 



wrfHinftYWrfciH <!.■■,! &5oAOH{!wkj):H1W-<W*} 



The Code Editor features adjustable Syntax Highlighting, Code Folding, Code 
Assistant, Parameters Assistant, Auto Correct for common typos and Code Tern 
plates (Auto Complete). 

The Code Explorer is at your disposal for easier project management. 
The Project Manager alows multiple project management 
General project settings can be made in the Project Settings window 
Library manager enables simple handling libraries being used in a project 
The Error Window displays all errors detected during compiling and linking. 
The source-level Software Simulator lets you debug executable logic step-by- 
step by watching the program flow. 

The New Project Wizard is a fast, reliable, and easy way to create a project. 
Help files are syntax and context sensitive. 

Like in any modern Windows application, you may customize the layout of 
mikroC PRO for PIC to suit your needs best. 

Spell checker underlines identifiers which are unknown to the project. In this way 
it helps the programmer to spot potential problems early, much before the proj- 
ect is compiled. Spell checker can be disabled by choosing the option in the 
Preferences dialog (F12). 
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CUSTOMIZING IDE LAYOUT 
Docking Windows 

You can increase the viewing and editing space for code, depending on how you 
arrange the windows in the IDE. 

Step 1: Click the window you want to dock, to give it focus. 



Project Manager 

%i£igi!ie@i<££fi% 



■jJQj LedBlinking.mcppi 

J -( nl Sources 

■ [3) LedBlinkJng.c 

;■■■■■£) Header Files 

JT^i Binaries 
;-■■£) Project level defines 
|-"£j Image Files 

£) Output Files 

O Other Files 



Step 2: Drag the tool window from its current location. A guide diamond appears. 
The four arrows of the diamond point towards the four edges of the IDE. 









Project Manager 




■6 


' 


i LedBlinking.mcppi 
i ■£) Sources 

= \ LedBlinkJng.c 
■■■■£j Header Files 
■-fei Binaries 

-{r^i Project level defines 
■-£} Image Files 
■-£) Output Files 


■~{CD Other Files 
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Step 3: Move the pointer over the corresponding portion of the guide diamond. An 
outline of the window appears in the designated area. 




Step 4: To dock the window in the position indicated, release the mouse button. 

Tip: To move a dockable window without snapping it into place, press CTRL while 
dragging it. 

Saving Layout 

Once you have a window layout that you like, you can save the layout by typing the 

name for the layout and pressing the Save Layout Icon |£j . 

To set the layout select the desired layout from the layout drop-down list and click 

the Set Layout Icon |bd] . 

To remove the layout from the drop-down list, select the desired layout from the list 

and click the Delete Layout Icon |£^ . 




vj Q lu lid 
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Auto Hide 

Auto Hide enables you to see more of your code at one time by minimizing tool win- 
dows along the edges of the IDE when not in use. 



■Click the window you want to keep visible to give it focus. 
■Click the Pushpin Icon s on the title bar of the window. 



■' LLi 







*e i suited 



J j^i FirstProject.mcppi 

a '£3 Sources 

; [^j Second Pro ject.c 

■ P^i Header Files 
!■■■■{□ Binaries 
j—tHl Project level defines 

■ P^i Image Files 
;■■■■■£) Output Files 

■fe Other Files 



G3HL& 



|b [13 Project Mana ||=| 



^3 FirstPro 

J G Soun 

1 1 I 

■■■■& Heac 
■■■■{P^ Binar 
■ ■■£) Proje 
■fr^l Innag 
■fe Outp 
-& Othe 



1° 110 l l^l l 



¥l_J 



fi 




When an auto-hidden window loses focus, it automatically slides back to its tab on 
the edge of the IDE. While a window is auto-hidden, its name and icon are visible 
on a tab at the edge of the IDE. To display an auto-hidden window, move your point- 
er over the tab. The window slides back into view and is ready for use. 
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ADVANCED CODE EDITOR 

The Code Editor is advanced text editor fashioned to satisfy needs of professionals. 
General code editing is the same as working with any standard text-editor, including 
familiar Copy, Paste and Undo actions, common for Windows environment. 

Advanced Editor Features 

■ Adjustable Syntax Highlighting 

■ Code Assistant 

■ Code Folding 

■ Parameter Assistant 

■ Code Templates (Auto Complete) 

■ Auto Correct for common typos 

■ Spell Checker 

■ Bookmarks and Goto Line 

■ Comment / Uncomment 



You can configure the Syntax Highlighting, Code Templates and Auto Correct from 
the Editor Settings dialog. To access the Settings, click Tools > Options from the 
drop-down menu, click the Show Options Icon 5? or press F1 2 key. 



Options 




f^l 


f Editor 


~~ 1 


Editor Settings 


U^ 




ST Restore Last Opened Project r Restore All Opened Files 
5ave Breakpoints V Save Bookmarks 




© Prompt for action '§' Reload File, but do not prompt O Ignore externally 


made changes 








R Enable Auto 5ave Timeout Interval: 3 [%J minutes 


Highlighter 

r Highlight begin.. end pairs 
Highlight brackets 




J Check Spelling 




© //(single lira) 




£jf Open options dialog 


Code Folding 
9 Enable code folding 
— 5how Ident Guides 
















OK Apply Cancel 
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Code Assistant 

If you type the first few letters of a word and then press Ctrl+Space, all valid iden- 
tifiers matching the letters you have typed will be prompted in a floating panel (see 
the image below). Now you can keep typing to narrow the choice, or you can select 
one from the list using the keyboard arrows and Enter. 



sp 



variabe s r 



char SP 



variable sfr unsigned char SPDR 
variable sfr unsigned char SPSR 
variable sfr unsigned char SPCR 

Code Folding 



Code folding is IDE feature which allows users to selectively hide and display sec- 
tions of a source file. In this way it is easier to manage large regions of code within 
one window, while still viewing only those subsections of the code that are relevant 
during a particular editing session. 

While typing, the code folding symbol ( - and + ) appear automatically. Use the fold- 
ing symbols to hide/unhide the code subsections. 



H 



void main ( ) { 



PORTA = 0; 
PORTB = 0; 
Lcd_Init ( ) ; 
LCD_Out ( 1 , 1 , txt [ 0] ) 
LCD_Out ( 2 , 1 , txt [ 1] ) 
delay_ms (1000) ; 
Lcd_Cmd(l) ; 

LCD_Out (1, l,txt[l] ) 
LCD_Out (2,1, txt [2] ) 
delay ms (500) ; 



void main(){ | | 



If you place a mouse cursor over the tooltip box, the collapsed text will be shown in 
a tooltip style box. 
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m 



void iwain(){ |_ Kq 



void main ( ) { 



PORTA = 0; 
PORTB = 0; 
Lcd_Init ( ) ; 
LCD_Out ( 1 , 1 , txt [ 0] ) 
LCD_Out ( 2 , 1 , txt [ 1] ) 
delay_ms (1000) ; 
Lcd_Cmd(l) ; 

LCD_Out (l,l,txt[l] ) 
LCD_Out ( 2 , 4 , txt [ 2 ] ) 
delay ma (500) ; 



Parameter Assistant 

The Parameter Assistant will be automatically invoked when you open parenthesis 
"(" or press Shift+Ctrl+Space. If the name of a valid function precedes the paren- 
thesis, then the expected parameters will be displayed in a floating panel. As you 
type the actual parameter, the next expected parameter will become bold. 



channel : char 



ADC Read 



Code Templates (Auto Complete) 

You can insert the Code Template by typing the name of the template (for instance, 
whiles), then press Ctrl+J and the Code Editor will automatically generate a code. 



You can add your own templates to the list. Select Tools > Options from the drop-down 
menu, or click the Show Options Icon ^J" and then select the Auto Complete Tab. Here 
you can enter the appropriate keyword, description and code of your template. 

Autocomplete macros can retreive system and project information: 

- %date% - current system date 

- %time% - current system time 

- %device% - device(MCU) name as specified in project settings 

- %device_clock% - clock as specified in project settings 

- %compiler% - current compiler version 
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These macros can be used in template code, see template ptemplate provided with 
mikroC PRO for PIC installation. 

Auto Correct 

The Auto Correct feature corrects common typing mistakes. To access the list of rec- 
ognized typos, select Tools > Options from the drop-down menu, or click the Show 
Options Icon ^ and then select the Auto Correct Tab. You can also add your own 
preferences to the list. 

Also, the Code Editor has a feature to comment or uncomment the selected code by sim- 
ple click of a mouse, using the Comment Icon {,,} and Uncomment Icon {,,} from 
the Code Toolbar. 

Spell Checker 

The Spell Checker underlines unknown objects in the code, so they can be easily 
noticed and corrected before compiling your project. 

Select Tools > Options from the drop-down menu, or click the Show Options Icon 
-3c and then select the Spell Checker Tab. 

Bookmarks 

Bookmarks make navigation through a large code easier. To set a bookmark, use 
Ctrl+Shift+number. To jump to a bookmark, use Ctrl+number. 

Goto Line 

The Goto Line option makes navigation through a large code easier. Use the short- 
cut Ctrl+G to activate this option. 

Comment / Uncomment 

Also, the Code Editor has a feature to comment or uncomment the selected 
code by simple click of a mouse, using the Comment Icon , * and Uncom- 
ment Icon {..} from the Code Toolbar. 
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CODE EXPLORER 



The Code Explorer gives clear view of each item declared inside the source code. 
You can jump to a declaration of any item by right clicking it. Also, besides the list of 
defined and declared objects, code explorer displays message about first error and 
it's location in code. 



Code Explorer 



J Functions 
: " CJrnain 
Globals 
TypeDef 
Tags 
Includes 



Following options are available in the Code Explorer: 



Icon 


Description 


If 


Expand/Collapse all nodes in tree. 


«N 


Locate declaration in code. 
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ROUTINE LIST 

Routine list diplays list of routines, and enables filtering routines by name. Routine 
list window can be accessed by pressing Ctrl+L. 

You can jump to a desired routine by double clicking on it. 
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ANSIIH - 0; 

THI9B - 0XF3J 

TSI3B - a*P?j 




// CQMJfrUI* AS fir* « JJfrJtJi j 



■■ Coafivu* **■> « outrut 



ICrKfl- IE3(]7W Fr 



JudsuMr; Hi hfi MM, l»i L:B 



Ch«l HOmbtf«<: KOTUTft! r«-*( ■! ■' ifr.W . 



^ 






J ftjIH. 

■ ■.', SPI 



-■ > : ■.-■■■ 

FuWH 

GbJ.FIFItr 



■ 



(■l^ragnm f,k ^knjtJumo^.H'.mikioL (KJ fai l'L'. l -.i.-.| 1 l- i ...p|-,r.-\i.aii[\SnuiwM 
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PROJECT MANAGER 



Project Manager is IDE feature which allows users to manage multiple projects. 
Several projects which together make project group may be open at the same time. 
Only one of them may be active at the moment. 

Setting project in active mode is performed by double click on the desired project 
in the Project Manager. 



Project Manager 



IEI 



lfi@ll£|£r|l*|» 



J-|JQ} LedBlinking.mcppi 

^■■■Ir^i Sources 

1 [Bj LedBlinkJng.c 

■■ {p^l Header Files 

■ICD Binaries 

4~"i Project level defines 

- f^l Image Files 
■*-■& Output Files 

3 LedBlinkJng.hex 

3 LedBlinkJng.asm 

lj LedBlinkJng.lst 

■■& Other Files 



Following options are available in the Project Manager: 
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Icon 


Description 


% 


Save project Group. 


ft 


Open project group. 


s 


Close the active project. 


^3 


Close project group. 





Add project to the project group. 


6 


Remove project from the project group. 


& 


Add file to the active project. 


& 


Remove selected file from the project. 


% 


Build the active project. 




Run mikroElektronika's Flash programmer. 



For details about adding and removing files from project see Add/Remove Files from 
Project. 

Related topics: Project Settings, Project Menu Options, File Menu Options, Project 
Toolbar, Build Toolbar, Add/Remove Files from Project 
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PROJECT SETTINGS WINDOW 

Following options are available in the Project Settings Window: 

■ Device - select the appropriate device from the device drop-down list. 

■ Oscillator - enter the oscillator frequency value. 

■ Build/Debugger Type - choose debugger type. 



Project Settings 
E\<g> Device 




Name: P16F887 



B^ Oscillator 



Value: 



8.000000 MH 



E) Build/ Debugger Type 



Build Type 
(* Release 

Debugger 



5 ICD Debug 



Related topics: Edit Project, Customizing Projects 
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LIBRARY MANAGER 



Library Manager enables simple handling libraries being used in a project. Library 
Manager window lists all libraries (extencion .mcl) which are instantly stored in the 
compiler Uses folder. The desirable library is added to the project by selecting check 
box next to the library name. 

In order to have all library functions accessible, simply press the button Check All 

J and all libraries will be selected. In case none library is needed in a project, 

press the button Clear All [ J and all libraries will be cleared from the project. 

Only the selected libraries will be linked. 



Library Manager 



% J U J 



[>□ 
•L2 
>H 
■>□ 
>B 
>H 
j 

:>□ 
-■□ 
-■□ 
•□ 
>H 

!■■■□ 

•□ 

>H 

j 

HH 

>m 
■ n 

>B 
>B 
>H 

■121 
>□ 

>n 

>H 

t>n 

■13 

»n 

;>□ 

&n 

>H 

>H 

j 



ADC 

Button 

CJIath 

C_Stdlib 

C_5tring 

C_Type 

CAN_SPI 

Compact_Flash_FAT16 

Compact_Flash 

Conversions 

EEPROM 

FLASH 

Glcd_Fonts 

Glcd 

EC 

Keypad4x4 

LcdJIonstants 

Led 

Manchester 

Mmc_FAT16 

Mmc 

One_Wire 

Port_Expander 

P52 

PWM12 

PWH3 

PWM45 

R5485 

Software_I2C 

Software_SPI 

SoftwareJJART 

Sound 

5PI_Ethernet 

SPI_Glcd 

SPI_Lcd 

SPI_Lcd8 

SPI_T6963C 

SPI 

Sprintf 

Sprinti 

Sprintl 

T6963C 

Time 

Trigonometry 

UART 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



45 



CHAPTER 2 

Environment 



mikroC PRO for PIC 



Icon 


Description 


1*1 


Refresh Library by scanning files in "Uses" folder. Useful when new 
libraries are added by copying files to "Uses" folder. 




- 




Rebuild all available libraries. Useful when library sources are available and 
need refreshing. 




Include all available libraries in current project. 


G 


No libraries from the list will be included in current project. 


a 


Restore library to the state just before last project saving. 



Related topics: mikroC PRO for PIC Libraries, Creating New Library 
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ERROR WINDOW 



In case that errors were encountered during compiling, the compiler will report them 
and won't generate a hex file. The Error Window will be prompted at the bottom of 
the main window by default. 

The Error Window is located under message tab, and displays location and type of 
errors the compiler has encountered. The compiler also reports warnings, but these 
do not affect the output; only errors can interefere with the generation of hex. 







B 





[rrors 


Warnings Hints 










Line 


Message No. 


Message Text 







1 


mikroCPIC1618.exe -M5F -DBG -pP16FS87 -UICD -C -Y -DL -011111114 -FoS -N"C:\Program Files\Mikroelektronika\mikroC PRO for PIC\Examples\5PI E 







125 


All files Preprocessed in 1 rns 







121 


Compilation Started 




2 


399 


; expected, but 'text' found 




2 


399 


^ iii-iip|. in. =' i 




2 


36B 


Specifier needed 




2 


393 


Invalid declarator expected'C or identifier 







102 


Finished (with errors): 09 Dec 2008, 10:04:01 
































< ppr t 



Double click the message line in the Error Window to highlight the line where the 
error was encountered. 

Related topics: Error Messages 
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STATISTICS 

After successful compilation, you can review statistics of your code. Click the Statis- 
tics Icon en I . 



Memory Usage Windows 

Provides overview of RAM and ROM usage in the various forms. 
RAM Memory Usage 

Displays RAM memory usage in a pie-like form. 



Statistics 
Enr.Hc.filt 



RAM Memory Usage 



r-DATft 




[J Used: MM bytes 21% 

^| fteer 391 bytes 79% 

Ttrtafc 4?6 bytes 


\ 79% 



Protect PJmie: C:\erogt wn FlwiMtiMlEWrortla'w^ioCW 
far PIOEiairplejtpevebpment 
System si E#yPTC5f GtedVGkd.mcfpl 



Ime: 2(^/2 D098:47;11AM 



VnW.Ht.FTrt ff n 
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Used RAM Locations 

Displays used RAM memory locations and their names. 



Used RAM Locations 



SFR Locations 

Displays list of used SFR locations. 





0x0070 


R0 


0x0064 


yy 


OXO0A4 


fi action 


0*0071 


Rl 


0x0065 


paga 


OxOOAfi 


x Mart 






0x0063 


j:i:veFonl 


OXO0A7 


x_enij 






0x0073 


R3 


0x0065 


aFwitwulth 


OxOOAS 


V_PC5 


0x0074 


R4 


0X0D66 


aFan eh eight 


OxO0A9 


CBlOf 


0X0075 


K5 


0X0D67 


















OxOOAG 


chf 


OxOOA6 


y_slart 






0*1X177 


K7 


<\«J<*7 


x_pos 


\:0<XX? 


V_rI1(t 


0x0079 


R8 


OxODAS 


page_num 


OxOOAS 


x_pos 






OXO0A9 


color 














OxO07A 


RIO 


OxODAA 


li 


OxDOAA 


loc 


(WW7B 


Rli 


OxOOAB 


rdata 










OX007C 


R12 


OxOOAC 


dsma 


0x0065 


y_cemer 


GxQWD 


ftl3 


G*EQAD 


nema 










DX007E 


KH 


OXODAE 


points i 










Qjd)07F 


R15 


0^0063 


Lexl 


OxOOdA 


tiwitdl 


0x0004 


FSRFTR 


0x0064 


(JCS 


OxOOfiC 


¥ 


0x0029 


?lstrl_fikd 


0x0065 


page_nu>n 


OxO0£E 


x 










OxOOAO 


d 










0X0039 


Tistra G\t6 


0K0D67 


i 


0X0063 


image 


DX0Q4A 


?IStr4_Gktt 


oxooeo 


<_po= 


0xQ065 


Ml 


3x00.53 


?lstrS_Gkd 


o*»oei 


y_po5 


3x00 St, 


P9 


0x0061 


n 


OxOOB.2 


color 


0x0067 


dwyiiza 










0x0055 


x_jppc-r_left 










0x0030 


DoICPAd'dr 


0xODB4 


bit maskO 


0x0064 


y_uppei_left 


0x0022 


fontW 


u -: us Li. 


cWata 


0x0065 


Octtoni_rHjht 



SFR Locations 













OxDO-OO 


INDF 


0x0013 


RXSDJlit 


OX0O9C 


P5SAC0_bit 


OxOODl 


TMRO 


oxooi a 


RCDSJj* 


OxOOOC 


P5SBDl_brt 


0x0002 


pa 


uxuijifj 


CCP?^_brl 


iav-JK. 


PS5BD0_bJt 


0x0003 


STATUS 


OxOOlD 


DC28l_blt 


0vOC9D 


STRSYNCJ* 


OX0OD4 


FSR 


OxDOlD 


cCP2r_bit 


0HHJ9C 


£TRD_biC 


OXOODA 


PCLATH 


OX0D1D 


OC2B0_.bit 


0*0/090 


STROKE 


OxCQDB 


]N7-:o--i 


OxOOlD 


CCP2M3_bit 


OsODSD 


STRBJtiI 


0x00 DC 


PIR1 


OxOOlO 


CCP2M2_bit 


0xOC9€ 


CTRAJlil 


OkOOOD 


PIR2 


OxOOlD 


CCP2MiJ)lt 


OjcOOSF 


rtDFMJjlt 


OxCODE 


TMR1L 


CxDOlD 


C_TF2M0_bit 


OxDOSF 


VCFGl_blt 


OxOOOF 


TMR1H 


OxODlF 


ADCS1 Jsit 


OxDODF 


VCFGOJbtt 


OxOOtO 


T1COM 


OaOOlF 


AD£S0_bit 


0x0105 


WDTPS3_blt 


0x0011 


TMR2 


DxDOlF 


CHS3_bit 


0x0105 


WDTPS2_bit 


OM012 


T2CQN 


OsODlF 


CHS2_bH 


0x0 105 


WDTPSljHC 


0.(00 1J 


5SPBUF 


OMJKLF 


CH5l_bit 


0X0105 


WDTPSOjM 


0x0014 


5SPCOM 


OnODlF 


CHSC_bi! 


0x0105 


SWDTENNt 


0x0015 


CCPR1L 


ftnOQlF 


GO_brt 


0x0107 


ClOtOit 


0x0016 


CCPR1H 


tartOiF | NOT_&ONE_b«t 


0x0107 


ClCuT_bit 


0x0017 


CCF1CON 


BxOOlF 


GO_fX)ME_blt 


0x0107 


ClCEjut 


0x0018 


RCS7A 


OxOOlF 


ADOHjit 


0x0107 


C1POL bit 


0x0019 


TXRK 


oxoogi 


MOT_RBPU_brt 


0x0107 


CIR_W 


JxOOlfl 


RCREG 


oxoo si 


INTEDG_b>t 


0x0107 


ClCHl_bit 


OxCOlB 


CCPfWL 


OxOOBl 


T0CS>t 


0x0107 


ClCHO_bit 


OxCOlC 


CCPR2H 


OxOOBl 














DxOfllD 


KP2CQN 


OxOOBl 


PSA bit 


0x01 08 


C30UT &it 


oxooie 


i^FSh 


OxOOBl 


iPS2_bit 


0x0108 


G2CF._bit 
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ROM Memory Usage 

Displays ROM memory space usage in a pie-like form. 



Function* Tr« 



ROM Memory Usage 



|-RCMUsaQB 

□ Used: 

□ F„ 

Totafc 


5759brtes 70% 
2433 brtK 30% 
3191 bvtes 




/ 70% 


/ 30% / 



Pio^trJmieiCilprogiMiFMMtifMkWimlaWToCPt 



Ime: 521/20093:47:1] AM 



ROM Memory Constants 

Displays ROM memory constants and their addresses. 



Statist) cs 
Ennttofilt 



ftifirtlo 12 Sorted 



ROM Memory Constants 







o-.'"s: 


?IC57lstfl_&lcd 


0x5787 


7K5^lstr2_6lcd 


fKL.-'i: 


?]CS?fcSr3_G<cd 


0x07A2 


?lCS?lstr4_aa] 


[■\[i,^S 


?lC$?lsBr5_GlHJ 


Dxaeao 


chauctersx? 


0k]5EA 


rciilSKT 


0.C-1C:; 


h)ntSystem5)i7_v2 


Q(0«BO 


EystemSxS 


QxiorjO 


twcl(Jimp 



Prajott Name: C:\trogi4m FI*slf*fMlektronla , iii*ioCPf 



■■-:.: i.-n:r-«iy-n 



Trtie:2(a^009B:47:llAM 



50 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 2 
Environment 



Function Sorted by Name 

Sorts and displays functions by their addresses, symbolic names, and unique 
assembler names. 



Functions Sorted By Name 



5rRLC<ati0fi 









OX0O6F 


DoICP 


D-OlCP 


0x0 IDS 










GftSQOS 


D* av_i0jj 


_Del3Y_iQus 


0x0118 


CuillV.lW 


_Delav_lus 


OXD013 


Dela^Ous 


_Delay_SGU'? 


OXD540 


delay25 


_delay25 


G*Q524 


Sled Sex 


ded eox 


0x0263 


Gkd_Qrcle 


_Glcd_.Grcte 


OxOOAl 










QXQ55D 


Gkd Fill 


Glcd_Hll 


0x0163 










0x0223 


Gkd_ Image 


_Clcd_lifiage 


MnBl 


Gkdjnrt 


jGkdJnit 


Cx037F 


SlcdjJn* 


_Glcd_Uns 


DXD0G4 


Gkd_ne.d_i>ata 


_Gcd_Read_Data 


0x0 1E2 


ijl.!j_f'.'ilSfl-jT 


_G;;d_Rei. tangle 


0x0i4t 


Skd_Set_fiwit 


_e cd_56l_^otrt 


0x0018 


Gkd_Set_Paoe 


_&[d_Sel_PaQ* 


0x0023 


Glcd_5*t_Slde 


_Glcd_S§l_5ide 


imn; 


Gkd_5«tJ< 


_GJcd_Sst_X 


OxOCFO 


Gkd v une 


CJcd v line 


9xo ue 


5kd_Wfite_Oiar 


_<Htd_Wrtle_0>ar 


0x0064 


5kd.Wnte.Data 


_Gkd_WnJe_Data 


CiaO-1E6 


Glcd_Write_T«rt 


G .:d_\',Ti1e_Text 


0x0550 










CxQWS 


MuL16xl6_U 


_Mul_ltal6_U 



Functions Sorted by Size 

Sorts and displays functions by their size, in the ascending order. 



Statistic 
Print to hit 



Functions Sorted By Size 





Dslay_lii5 


_Delay_lLts 


3 


Del3y_5QUS 


_Delay_5au5: 


5 


Delay_10us 


_Del3j-_'Luu* 


6 


DoICP 


DoICP 


7 


Strobe 


_ub Gkd snob* 


e 


L.I.J V.iiW Data 


Gkd '/.ute Data 


ii 


Clcti_V,lltia_DiU 


_Gkd_'.Vi&E_Data 


n 












14 






Gltd_Set_FrwiI 










GkdL5et_side 










GledLSeLX 










Gkd_P*adJ)a» 










Gkd_ftea<i_DaEa 


_ckd_Read_Oata 


25 


Gkd_v_uri« 


_Gkd_v_ui» 


27 


Gkd V Line 


Gkd V Line 


.■■ 


Gkd.Box 


JjkrtJJo* 


;s 


ekd_Wril*_Text 


_dikd_Wite_.Text 


3? 


HlI 16x16 U 


hjI lontie u 


43 


Gkd Fill 


Gkd_nll 


51 


Gkd_Init 


_Gl<dJnit 


53 


Gkd_R« tangle 


_Gkd._fUctanslB 


70 


Gkd_ Image 


„Gk damage 


94 


Gkd_Dot 


_Gkd_Bot 


92 


Gkd Write Cha< 


Gkd Write Char 


150 


GlctLOde: 


_Gkd_Gircle 


252 
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Functions Sorted by Addresses 

Sorts and displays functions by their addresses, in the ascending order. 



Satirfki 




1 




Ennttofil* 




RAM Memory 

SfRLOMCions 

ROM Memory 
Usaot 

flOM Memory 
cans [aim 

B, Mltftt 

Functions ssned 

Functions Suited 
By Address 


Functions Sorted By Address 




faflDflS 








Dalau_LOiE 


_Delay_lQus 




(MiDoa 


Strobe 


Lib Gleri Sbraie 




tt*0Q13 


Dslay_»us 


_Delay_5Qus 




fedO'ia 


Gkd_Set_Page 


_GEcd_SeLPage 




OhG023 


Glcd_Se^.Side 


_Gltd^et_5id# 




OxOaiM 


Gled_Re-ad_Dala 


_Gltd_R« ad_Da ta 




0*0040 


Glcd Set X 


Gled Set_X 




OxOOM 


Glcd_Write_Oata 


_Glol_Write_Data 




CscOOSF 






























OxOOFD 


GkeLVJJne 


_Glr.d_V_Lirie 




Fjncticns Sorted 
BY Ham* Chart 

Functions Sorted 
B*Sm Chart 

Functions Sorted 
By flddresa Chart 

Function* Tr.« 
5umrn*nf 


taD]l8 


Delay_lus 


_Delay_lu5 




IbdllB 


filcd_Wnte_Char 


_Gltd_WNte_Char 




(MJIBB 


Glcd h Line 


Gkd_h Line 




0x0106 


_CC20W 


CC2DW 




(M91E2 


Gkdjtertangle 


_GkdJfertaii"ki 




0x0228 


Glcdjrciage 


_Glod_[mage 




03(0293 


Glcd_Cif£le 


_Glod_Qrd8 




O.X037F 


Gkd_Line 


_Gkdj_lne 








jGlcdJnit 










OrtHEG 


GkdJiVrtB_Twt 


_GI(il_WrilK_Te«t 




OxOSftB 


Mul_B»SJJ 


JA\i\JSxBJJ 




0x0524 


Glcd_BCr* 


_Glcd_Hi3x 




0x0540 


delay 25 


_defay2S 




Ox054E 


Gkd_Set_Fort 


jG!cd_=.«_F;!nt 













Functions Sorted by Name Chart 

Sorts and displays functions by their names in a chart-like form. 



EnriHofilt 



Constant 
Functions Sorted 



Function* T(« 



FincSicns swIsdfcyNr 




Gledjyjne 
I-bdJn-agfr 



Glcd_R«ClBnglt 
Glcd_5d_Fcfrl 
Gfcfl_sa_Page 




I 33 Ww? I 



L^2*£^sil 






- r ■ ' 



__ I ,.-;■■■■•■, | 




| ■ iM-i-.l] 



'D ■' ■ .- . | 



Z I TO- lt-t*i) 



KO 210 iO !5) 286 300 



Project Nsne: C:\Pfoor am FI«\r*roeleFtronlta , unq'oCFnC> 



Trne:2J2^pOCBa:47:llAM 
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Functions Sorted by Size Chart 

Sorts and displays functions by their sizes in a chart-like form. 



CftB*!Aft» 

Functions swted 




fro|stit (Abb: Ci^rogtwn Flw'i|r<ToaleWronla'iml , ToCR 



Tme: 2J21/2HS 9:57:44 AM 



Functions sorted by Address Chart 

Sorts and displays functions by their addresses in a chart-like form. 



Statistic* 
Enrttofilt 



FuPrtian* Sansd 



Fiinctlfli*TiM 



3nti_ri 

«cdjto< 

WJ_3iS_J 

Ofcl_WH«.T»-c 

Ctd_rt 

_CCJOW 

GUJ. .LIU 



OtcriUSStjt 

Glect.SeLSde 
i-'cd 



Funttcrii sot «t tyy Addre-ss 



Br 

■ O v 



^o^tNaiie:C:lfragi^FI«ir«TMte^trof>*a , iiii^oCff 



I(ne:2(Mpom 9:57:41 AM 
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Function Tree 

Displays Function Tree with the relevant data for each function. 



Statistics 
Ennttofil* 



E^JfJAl] [tdlwHI 



iTjfictlorK Sorted 



Glcd_SBt_Fcfit 
* Gk4_W,teJ*A 
■• 5td_wt.e_Ch* 

* ad_5el_K 

m strata 

MI*y_LPl)S 

* <3:d_5«tJ'*g' 

* Slrftt* 

Detay_lOus 
t4d_SM_Sde 

j t3:d_ftftKl_[>8ta 

DdSy_5fti! 

- C3Ld_WrKa_Dal* 

J Strote 

MuU6k16_U 
ra nTT> 

* GkoJXrt 

t5tdjat_*)e 



j ■L'.:d_E. 






J Strobe 

Delay_LOu£ 

* ■Sdjotji 

- 3rote 

Delay_LOiK 

* gfed_Ft40»W 

Delay_5&>s 
- ad_W, t*_Oati 

- arete 

DeW_L0uS 

< _ccayiw 

Md EW9 U 



Functions Tree 



ure; 


_W_OkI-c 


~o."ri^ Name 


_Ocd_Crde 


Real P.oJfrie Nam* 


<*d_Crrfe 


-'.-.: *■: -■:■:■ i.b ■■.: ;;. 


SS2 


Return typ*: 


«4d 


Routine Sort Mdrcss: 


643 


-4:if:E-dftiMi 


s;= 


curifrt: Depth: 


i 


Max S«k Depth: 


& 


C«l Fraquftncy: 


■r^ 



- fK03?F 




■■-■■■.■■ .■■Tir-r-': fr.-n 



Memory Summary 

Displays summary of RAM and ROM memory in a pie-like form. 



Statistics 
Ennfctofilt 



Summary 



Q Uteds 

Lj *» 

Totd: 


KHbrte* 21% 
391 bytes 79 K 
•195 bytes 






\ 79% 


21% 





Q Used 

Q Fre& 

Total 


bvles 575S fy, to 
b¥les2t33 % 30 

bytes 8151 




/ 70% \ 


/ 30% / 



Project Nm*: C:\Progt «n FtatMtaKlcMrwilcatyrtroCK 

far : 1C'!E;-arc(es*pev«lcpiip"nt 
System s| E-ss yPK^ Of dWW.mtfpl 



IH*:2|a i r2fflHa:57:-'HAM 
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MACRO EDITOR 



A macro is a series of keystrokes that have been 'recorded' in the order performed. 
A macro allows you to 'record' a series of keystrokes and then 'playback', or repeat, 
the recorded keystrokes. 



Macros 
*X L 




Name 
Macro3 



' 



3 



The Macro offers the following commands: 



Icon 


Description 


■o 


Starts 'recording' keystrokes for later playback. 


a: 


Stops capturing keystrokesthat was started when the Start Recordig com- 
mand was selected. 


(►§■ 


Allows a macro that has been recorded to be replayed. 


# 


New macro. 


© 


Delete macro. 



Related topics: Advanced Code Editor, Code Templates 
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INTEGRATED TOOLS 
USART Terminal 



The mikroC PRO for PIC includes the USART communication terminal for RS232 
communication. You can launch it from the drop-down menu Tools > USART Termi- 
nal or by clicking the USART Terminal Icon □, from Tools toolbar. 



RS232 Terminal 
Settings — 



@ 



Corn Port:|!COM3 
Baud: 



9600 



Stofi Bits: One Stop Bit 



Parity: 



None 



Check Parity 



Data bits: Eight 



Cornrnands- 
RIS — 
a Off 
On 



■DTR — 
® Off 
On 



Disconnect 



Status 








Send 


Receive 


CTS 


DSR 


« 


« 


« 


« 



-Log Files 

Read from: 

Write to: 

•/ Append to 



*" 



J Create file 



Cornrnunication- 



Echo 

Append: CR 
LF 

■Receive data as- 
§ ASCII 



iend 



Send 
File 



Send as typing 
Send as number 



Start Logging 
Clear Hjstory 



HEX 



DEC 



Connected to COM3 
Sent: Echo 
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EEPROM Editor 

The EEPROM Editor is used for manipulating MCU's EEPROM memory. You can 
launch it from the drop-down menu Tools > EEPROM Editor. When Use this 
EEPROM definition is checked compiler will generate Intel hex file 
project name. ihex that contains data from EEPROM editor. 

When you run mikroElektronika programmer software from mikroC PRO for PIC IDE 

-projectname.hex file will be loaded automatically while ihex file must be loaded 
manually. 



mikroElektronika EEPROM Tool 



\L EEPROM Editor 



[~~l Use Eeprom in project 



Help 



EEPROM Size: 



EEPROM Fill: 



EEPROM File 



Bytes Value: Ok FF Fill 



EEPROM Data 




Addr 


|00 


01 


U2 


03 


04 


01 


Ob 


0/ 


00 


oy 


OA 


00 


OL 


OU 


Ob 


Oh 


Char 


■ ' 




FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


u 




FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 




FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 




FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 




FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


0050 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


0060 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


0070 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


0080 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


0090 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


FF 


yyyyyyyyyyyyyyyy 


1' 



EEPROM Edit: 
Input Format: 

C' Dec 
% Hen 
O Float 
(_: String 



EEPROM Address: 
Start Address: Ok FFFF 
[Vl Autolnc 



Edit Value: 


Hex No: Ok 




Edit 


„. 


O Byte 


Word 


C« DWord 
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ASCII Chart 

The ASCII Chart is a handy tool, particularly useful when working with Led display. 
You can launch it from the drop-down menu Tools > ASCII chart or by clicking the 
View ASCII Chart Icon from Tools toolbar. 



_ 

Ascii Chart 




























@ 







1 


2 


3 


4 


5 


6 


7 


B 


9 


A 


B 


C 


D 


E 


F 







NUL 


SOH 


STX 


ETX 


EOT 


ENQ 


ACK 


BEL 


BS 


HT 


LF 


VT 


FF 


CR 


SO 


SI 







1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 




1 


DLE 


DC1 


DC2 


DC3 


DC4 


NAK 


SVN 


ETB 


CAN 


EM 


SUB 


ESC 


FS 


GS 


RS 


US 




16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 




2 


SPC 


! 


" 


# 


$ 


% 




■ 


( 


) 


* 


+ 


r 


- 




/ 




32 


33 


34 


35 


36 


37 


38 


39 


40 


41 


42 


43 


44 


45 


46 


47 




3 





1 


2 


3 


4 


5 


6 


7 


B 


9 




I 


< 


= 


> 


? 




48 


49 


50 


51 


52 


53 


54 


55 


56 


57 


58 


59 


60 


61 


62 


63 




4 


@ 


A 


B 


C 


D 


E 


F 


G 


H 


I 


J 


K 


L 


M 


N 


O 




64 


65 


66 


67 


68 


69 


70 


71 


72 


73 


74 


75 


76 


77 


78 


79 




5 


P 


Q 


R 


S 


T 


U 


V 


W 


X Y 


Z 


[ 


\ 


] 


J\ 


_ 




80 


81 


82 


83 


84 


85 


86 


87 


88 89 


90 


91 


92 


93 


94 


95 




6 


* 


a 


b 


C 


d 


e 


f 


g 


104? 
* 




J 


k 


1 


m 


n 


O 




96 
P 


97 


98 


99 


100 


101 


102 


103 




H fS- 


1 


]7 


108 


109 


110 


111 




CHR: h 
DEC: 104 




7 


q 


r 


S 


t 


u 


V 


W 


r 
L 


1 


} 


**i 


DEL 




112 


113 


114 


115 


116 


117 


118 


119 


120 


HEX: 0x68 
3IN: 0110 1000 


13 


124 


125 


126 


127 




G 


€ 
128 


129 


J 

130 


/ 

131 


JJ 

132 


133 


t 
134 


t 
135 


136 


' 


CE 

140 


141 


Z 
142 


143 


137 


138 


139 


9 




l 


J 


U. 


II 


• 


- 


— 


"""■ 


TM 


S 


> 


oe 




Z 


Y 




144 


145 


146 


147 


148 


149 


150 


151 


152 


153 


154 


155 


156 


157 


158 


159 




A 




i 


It 


£ 


n 


¥ 


! 


§ 




© 


a 


« 


- 1 


- 


® 






160 


161 


162 


163 


164 


165 


166 


167 


168 


169 


170 


171 


172 


173 


174 


175 






o 


± 


2 


3 


' 


P 


1 




j 


1 


D 


» 


1/4 


1/2 


% 


i 


7- 


176 


177 


178 


179 


180 


181 


182 


183 


184 


185 


186 


187 


188 


189 


190 


191 




A 


A 


A 


A 


A 


A 


ff 


c 


E 


E 


E 


E 


I 


I 


I 


I 




192 


193 


194 


195 


196 


197 


198 


199 


200 


201 


202 


203 


204 


205 


206 


207 




D 


D 


N 

















X 


D 


u 


u 


u 


u 


Y 


r> 


B 




208 


209 


210 


211 


212 


213 


214 


215 


216 


217 


218 


219 


220 


221 


222 


223 




E 


a 


a 


a 


a 


a 


H 


ae 


S 


e 


e 


e 


e 


i 


1 


1 


r 




224 


225 


226 


227 


228 


229 


230 


231 


232 


233 


234 


235 


236 


237 


238 


239 




F 


d 


n 


O 


6 


6 


6 


6 


+ 





U 


U 


U 


ij 


V 


P 


V 




240 


241 


242 


243 


244 


245 


246 


247 


248 


249 


250 


251 


252 


253 


254 


255 


J 
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Seven Segment Converter 

The Seven Segment Convertor is a convenient visual panel which returns 
decimal/hex value for any viable combination you would like to display on 7seg. 
Click on the parts of 7 segment image to get the requested value in the edit boxes. 
You can launch it from the drop-down menu Tools > 7 Segment Convertor or by 
clicking the Seven Segment Convertor Icon F. from Tools toolbar. 



Seven Segment Editor 



Common cathode: 




LCD Custom Character 



mikroC PRO for PIC includes the Led Custom Character. Output is mikroC PRO for 
PIC compatible code. You can launch it from the drop-down menu Tools > Led Cus- 
tom Character. 



=3 



LCD custom character 



ft it 

5x7 



5 h 10 



Save.. 



□□□□□ 
□□□□□ 

■ 
■■■■■ 

□□■□□ 

:■: 
□□□□□ 



m B" D Q 

Load... Fill all Clear all Invert 



Font 

* |5 :•: 7 * cursor lind 

f~ 5 y 10 + cursor line 



Preview: 



CGRAM address 
Char: 
Char data row: 



GENERATE 



fi+B 


1° sf 

1? 2f 
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Graphic LCD Bitmap Editor 

The mikroC PRO for PIC includes the Graphic Led Bitmap Editor. Output is the 
mikroC PRO for PIC compatible code. You can launch it from the drop-down menu 
Tools > Glcd Bitmap Editor. 




// GLCD Picture name: truck.bmp 
// GLCD Model: KS0108 128x64 
// 



const truck_bnp : 

0, 0, 0, 0, 

12, 10. 10. 10. 

9, 9, 9, 9, 



array [1824] of byte 
0,248. 8, 8, 

10, 10, 10, 9, 
9, 9, 9, 9 



137,137,137,137,137,137,137, 9, 
9, 9, 13,253, 13,195, 6,252, 
0, 0, 0, 0, 0, 0, 0, 0, 



8. 


8, 8, 8, 12, 12, 12, 12, 




9. 


9, 9, 9, 9, 9, 9, 9, 




9. 


9,137,137,137,137,137,137, 




9. 


9, 9, 9, 9, 9, 9, 9, 




0. 


0, 0, 0, 0, 0, 0, 0, 




0, 


0, 0, 0, 0, 0, 0, 0, 


-r 



ver: 2.0.1 -27012005 



System status.: Win NT like OS 
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HID Terminal 

The mikroC PRO for PIC includes the HID communication terminal for USB commu- 
nication. You can launch it from the drop-down menu Tools > HID Terminal. 



mikroElektronika USB (HID) Terminal 



s 1-^a.l 



Terminal Descriptor 



Info 



ABBAHOME 
ABBAHOME 



Dell Premium USB Optical House 



Communication 



|HID Read/Write Test 

\7 5end as Typing 
I - 5end as Number 



Format 
C ASCII 



P HEX 



C DEC 



Send 
Clear 



HID Read/Urite Test 
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UDP Terminal 



The mikroC PRO for PIC includes the UDP Terminal. You can launch it from the 
drop-down menu Tools > UDP Terminal. 



3^ UDP Communication Terminal 


mi^i 










IP Address: 
Port: 


192.1S8.20.25 


Connect | 


10001 














IrnikroElektronika 


Send 


Append: I - CR \~ Send as typing 
I - LF I - Send as number 


IrnikroElektronika 




4 


► 




Gear 


r 




<• ASCII r HEX r DEC 




1 


t 


► 
















Cleaj 











62 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 2 
Environment 



mikroBootloader 

(From Microchip's document AN732) The PIC1 6F87X family of microcontrollers has 
the ability to write to their own program memory. This feature allows a small boot- 
loader program to receive and write new firmware into memory. In its most simple 
form, the bootloader starts the user code running, unless it finds that new firmware 
should be downloaded. If there is new firmware to be downloaded, it gets the data 
and writes it into program memory. There are many variations and additional fea- 
tures that can be added to improve reliability and simplify the use of the bootloader. 

Note: mikroBootloader can be used only with PIC MCUs that support flash write. 

How to use mikroBootloader? 



1 . Load the PIC with the appropriate hex file using the conventional programming 
techniques (e.g. for PIC16F877A use pi6f877a.hex). 

2. Start mikroBootloader from the drop-down menu Tools > Bootoader. 

3. Click on Setup Port and select the COM port that will be used. Make sure that 
BAUD is set to 9600 Kpbs. 

4. Click on Open File and select the HEX file you would like to upload. 

5. Since the bootcode in the PIC only gives the computer 4-5 sec to connect, you 
should reset the PIC and then click on the Connect button within 4-5 seconds. 

6. The last line in then history window should now read "Connected". 

7. To start the upload, just click on the Start Bootloader button. 

8. Your program will written to the PIC flash. Bootloader will report an errors that 
may occur. 

9. Reset your PIC and start to execute. 



Q :: mikroElektronika :: mikroBootloader vl.0,0,2 
History Window 



Opened: C:\Prograrn Files\MikroelektronikaWiikroC PRO for 
■ PIC\E xarnples\D eveloprnent Systerns\E asyPI C5\Lcd\Lcd. hex 



- Terminal Window 





Open HEX file 



Start bootloader 



• • # 

Connect Tx Rx 



CAProgram Files^MikroelektronikaVmikroC PRO for PI C^Exarnples^D eveloprnent Systems^ asyPICSMcil'' 
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Features 

The boot code gives the computer 5 seconds to get connected to it. If not, it starts 
running the existing user code. If there is a new user code to be downloaded, the 
boot code receives and writes the data into program memory. 

The more common features a bootloader may have are listed below: 

■ Code at the Reset location. 

■ Code elsewhere in a small area of memory. 

■ Checks to see if the user wants new user code to be loaded. 

■ Starts execution of the user code if no new user code is to be loaded. 

■ Receives new user code via a communication channel if code is to be loaded. 

■ Programs the new user code into memory. 

Integrating User Code and Boot Code 

The boot code almost always uses the Reset location and some additional program 
memory. It is a simple piece of code that does not need to use interrupts; therefore, 
the user code can use the normal interrupt vector at 0x0004. The boot code must 
avoid using the interrupt vector, so it should have a program branch in the address 
range 0x0000 to 0x0003. The boot code must be programmed into memory using 
conventional programming techniques, and the configuration bits must be pro- 
grammed at this time. The boot code is unable to access the configuration bits, 
since they are not mapped into the program memory space. 
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OPTIONS 

Options menu consists of three tabs: Code Editor, Tools and Output settings. 

Code editor 

The Code Editor is advanced text editor fashioned to satisfy needs of professionals. 

Tools 

The mikroC PRO for PIC includes the Tools tab, which enables the use of shortcuts 
to external programs, like Calculator or Notepad. 

You can set up to 10 different shortcuts, by editing ToolO - Tool9. 



Tools 
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Output settings 

By modifying Output Settings, user can configure the content of the output files. 

You can enable or disable, for example, generation of ASM and List file. 

Also, user can choose optimization level, and compiler specific settings, which 

include case sensitivity, dynamic link for string literals setting (described in mikroC 

PRO for PIC specifics). 

Build all files as library enables user to use compiled library (* .mci) on any PIC 

MCU (when this box is checked), or for a selected PIC MCU (when this box is left 

unchecked). 

For more information on creating new libraries, see Creating New Library. 



Option; 



■■' Generate / . :■'■".. 

V Include HESi 

'■/ Include ROM constants 

V Include ROM Addresses 

V Generate list file 

V Include debug info 

7 Include source lines in output files 
Optimization level: 



Compiler 

W casesensli 

J Dynamic link foe string literals 

■/ Build ell Files as library 



I ^ PP ' V I 



Cancel 
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Introduction 

Regular Expressions are a widely-used method of specifying patterns of text to 
search for. Special metacharacters allow you to specify, for instance, that a particu- 
lar string you are looking for, occurs at the beginning, or end of a line, or contains n 
recurrences of a certain character. 

Simple matches 

Any single character matches itself, unless it is a metacharacter with a special 
meaning described below. A series of characters matches that series of characters 
in the target string, so the pattern "short" would match "short" in the target string. 
You can cause characters that normally function as metacharacters or escape 
sequences to be interpreted by preceding them with a backslash "\". 
For instance, metacharacter " A " matches beginning of string, but "\ A " matches 
character " A ", and "\\" matches "\", etc. 

Examples: 

unsigned matches string 'unsigned' 
\ A unsigned matches string '^unsigned' 

Escape sequences 

Characters may be specified using a escape sequences: "\n" matches a newline, 
"\t" a tab, etc. More generally, \xnn, where nn is a string of hexadecimal digits, 
matches the character whose ASCII value is nn. 

If you need wide (Unicode) character code, you can use T \x{nnnn} ', where 'nnnn' 
- one or more hexadecimal digits. 

\xnn - char with hex code nn 

\x{nnnn) - char with hex code nnnn (one byte for plain text and two bytes for Unicode) 

\t - tab (HT/TAB), same as \x09 

\n - newline (NL), same as \xOa 

\r - car.return (CR), same as \xOd 

\f - form feed (FF), same as \xOc 

\a - alarm (bell) (BEL), same as \x07 

\e - escape (ESC) , same as \x1b 
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Examples: 

unsigned\x20int matches 'unsigned int ' (note space in the middle) 
\tunsigned matches 'unsigned' (predecessed by tab) 

Character classes 

You can specify a character class, by enclosing a list of characters in [], which will 
match any of the characters from the list. If the first character after the "[" is " A ", the 
class matches any character not in the list. 

Examples: 

count[aeiou] r finds strings ' countar ' , 'counter', etc. but not 

' countbr ' , ' counter ' , etc. 

count[ A aeiou]r finds Strings 'countbr', 'counter', etc. but not 

' countar ' , ' counter ' , etc. 

Within a list, the "-" character is used to specify a range, so that a-z represents all 
characters between "a" and "z", inclusive. 



If you want "-" itself to be a member of a class, put it at the start or end of the list, or 

precede it with a backslash. 

If you want ']', you may place it at the start of list or precede it with a backslash. 

Examples: 

[-az] matches 'a', 'z' and '-' 

[az-] matches 'a', 'z' and '-' 

[a\-z] matches 'a', 'z' and '-' 

[a-z] matches all twenty six small characters from 'a' to 'z' 

[\n-\xOD] matches any of #10, #11, #12, #13. 

[\d-t] matches any digit, '-' or 't'. 

[] -a] matches any char from ' ] ' . . 'a' . 

Metacharacters 

Metacharacters are special characters which are the essence of regular expres- 
sions. There are different types of metacharacters, described below. 
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Metacharacters - Line separators 

A - start of line 

$ - end of line 

\A - start of text 

\Z - end of text 

. - any character in line 

Examples: 

"porta - matches string porta " only if it's at the beginning of line 
porta$ ■ matches string ' porta " only if it's at the end of line 
^porta$ ■■ matches string porta ' only if it's the only string in line 
port . r - matches strings like ' porta ' , ' portb ' , ' porti ' and so on 

The " A " metacharacter by default is only guaranteed to match beginning of the input 

string/text, and the "$" metacharacter only at the end. Embedded line separators 

will not be matched by A " or "$". 

You may, however, wish to treat a string as a multi-line buffer, such that the " A " will 

match after any line separator within the string, and "$" will match before any line 

separator. 

Regular expressions works with line separators as recommended at http://www.uni- 

code.org/unicode/reports/tr1 8/ 

Metacharacters - Predefined classes 

\w - an alphanumeric character (including "_") 

\W - a nonalphanumeric character 

\d - a numeric character 

\D - a non-numeric character 

\s - any space (same as [\t\n\r\f]) 

\S - a non space 

You may use \w, \d and \s within custom character classes. 

Example: 

routi\de - matches strings like ' routile ' , ' routi6e ' and so on, but not 
'routine', ' routime ' and SO on. 
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Metacharacters - Word boundaries 

A word boundary ("\b") is a spot between two characters that has an alphanumeric 
character ("\w") on one side, and a nonalphanumeric character ("\W") on the other 
side (in either order), counting the imaginary characters off the beginning and end 
of the string as matching a "\W". 

\b - match a word boundary) 
- match a non-(word boundary) 

Metacharacters - Iterators 

Any item of a regular expression may be followed by another type of metacharac- 
ters - iterators. Using this metacharacters.you can specify number of occurences of 
previous character, metacharacter or subexpression. 

* - zero or more ("greedy"), similar to {0,} 

+ - one or more ("greedy"), similar to {1 ,} 

? - zero or one ("greedy"), similar to {0,1} 

{n} - exactly n times ("greedy") 

{n,} - at least n times ("greedy") 

{n,m} - at least n but not more than m times ("greedy") 

*? - zero or more ("non-greedy"), similar to {0,}? 

+? - one or more ("non-greedy"), similar to {1 ,}? 

?? - zero or one ("non-greedy"), similar to {0,1}? 

{n}? - exactly n times ("non-greedy") 

{n,}? - at least n times ("non-greedy") 

{n,m}? - at least n but not more than m times ("non-greedy") 

So, digits in curly brackets of the form, {n,m}, specify the minimum number of times 
to match the item n and the maximum m. The form {n} is equivalent to {n,n} and 
matches exactly n times. The form {n, } matches n or more times. There is no limit 
to the size of n or m, but large numbers will chew up more memory and slow down 
execution. 

So, digits in curly brackets of the form, {n,m}, specify the minimum number of times 
to match the item n and the maximum m. The form {n} is equivalent to {n,n} and 
matches exactly n times. The form {n, } matches n or more times. There is no limit 
to the size of n or m, but large numbers will chew up more memory and slow down 
execution. 

If a curly bracket occurs in any other context, it is treated as a regular character. 
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Examples: 

count. *r fi- matches strings like 'counter', 'countelkjdflkj9r ' and 

' countr ' 

count. +r - matches strings like 'counter', 'countelkjdflkj9r ' but not 

' countr ' 

count. ?r - matches strings like 'counter', 'countar' and 'countr' but not 

'countelkj9r' 

counte{2}r - matches string 'counteer' 

counte{2,}r - matches Strings like 'counteer', 'counteeer', 'counteeer' etc. 

counte{2,3}r - matches strings like 'counteer', or 'counteeer' but not 

' counteeeer ' 

A little explanation about "greediness". "Greedy" takes as many as possible, "non- 
greedy" takes as few as possible. 

For example, 'b+' and 'b*' applied to string abbbbc' return bbbb', 'b+?' returns 'b', 
'b*?' returns empty string, 'b{2,3}?' returns 'bb', 'b{2,3}' returns 'bbb'. 

Metacharacters - Alternatives 

You can specify a series of alternatives for a pattern using " | " to separate them, 
so that bit | bat | bot will match any of "bit" , "bat", or "bot" in the target string 
as would "b(i|a|o)t) ". The first alternative includes everything from the last pat- 
tern delimiter ("(", "[", or the beginning of the pattern) up to the first "|",and 
the last alternative contains everything from the last " | " to the next pattern delim- 
iter. For this reason, it's common practice to include alternatives in parentheses, to 
minimize confusion about where they start and end. 

Alternatives are tried from left to right, so the first alternative found for which the 
entire expression matches, is the one that is chosen. This means that alternatives 
are not necessarily greedy. For example: when matching rou|rout against "rou- 
tine", only the "rou" part will match, as that is the first alternative tried, and it 
successfuly matches the target string (this might not seem important, but it is impor- 
tant when you are capturing matched text using parentheses). Also remember that 
" | " is interpreted as a literal within square brackets, so if you write [ bit | bat | bot] , 
you're really only matching [biaoi ] . 



Examples: 

rou (tine | te) - matches strings 'routine' or 'route' 
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Metacharacters - Subexpressions 

The bracketing construct (...) may also be used for define regular subexpres- 
sions. Subexpressions are numbered based on the left to right order of their open- 
ing parenthesis. First subexpression has number ' l ' . 



Examples: 

(int) {8,10} matches strings which contain 8, 9 or 1 instances of the 'int' 

routi([0-9] |a+)e matches 'routiOe 1 , 'routile' , 'routine 1 , 'routinne', 
'routinnne' etc. 



Metacharacters - Backreferences 

Metacharacters \i through \9 are interpreted as backreferences. matches previ- 
ously matched subexpression #. 



Examples: 

( . ) \i+ matches 'aaaa' and 'cc'. 

( . +) \i+ matches 'abab' and '123123' 

(['"]?) (\d+)\i matches "13" (in double quotes), or '4 ■ (in single quotes) 

or 77 (without quotes) etc. 
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mikroC PRO for PIC COMMAND LINE OPTIONS 

Usage: mikroCPIC1618.exe [ -<opts> [ -<opts>] ] [ <infile> [ -<opts>] ] [ - 

<opts>] ] Infile can be of * .c, * .mci and * .pid type. 

The following parameters and some more (see manual) are valid: 

- p: MCU for which compilation will be done. 

- fo: Set oscillator [in MHz]. 

- sp: Add directory to the search path list. 

- if: Add directory to the #include search list. 

- n: Output files generated to file path specified by filename. 

- b: Save compiled binary files (* .mci) to 'directory'. 

- o: Miscellaneous output options. 

- dbg: Generate debug info. 

- l: Check and rebuild new libraries. 

- d: Build all files as libraries. 

- y: Dynamic link for string literals. 

- c: Turn on case sensitivity. 

- ucd: ICD build type. 

Example: 

mikroCPIC1618.exe -MSF -DBG -pl6F887 -ES -C -011111114 -fo8 - 
N"C: \Lcd\Lcd . mcppi " -SP"C: \Program Files\Mikroelektronika\mikroC PRO 
for PIC\Defs\" -SP"C: \Program Files\Mikroelektronika\mikroC PRO for 

PIC\Uses\P16\" -SP"C:\Lcd\" "Lcd.c" " Lib_Math.mcl" 

" Lib_MathDouble .mci" " Lib_System.mcl" " Lib_Delays .mci" 

" Lib_LcdConsts .mci" " Lib_Lcd.mcl" 

Parameters used in the example: 

- msf: Short Message Format; used for internal purposes by IDE. 

- dbg: Generate debug info. 

- P i6F887: MCU 16F887 selected. 

- c: Turn on case sensitivity. 

- 011111H4: Miscellaneous output options. 

- foio: Set oscillator frequency [in MHz]. 

-N"C:\Lcd\ Led. mcppi" -SP"C:\ Program Files\Mikroelektronika\mikroC PRO 

for pic\def s\ ": Output files generated to file path specified by filename. 

- -SP"C:\Program Files\Mikroelektronika\ mikroC PRO for PIC\ 

def s\ ": Add directory to the search path list. 

- SP"C:\ Program Files\ Mikroelektronika\mikroC PRO for PIC \uses\": 

Add directory to the search path list. 

- -SP"C:\Lcd\": Add directory to the search path list. 

-"Lcd.c" " Lib_Math.mcl" " Lib_MathDouble . mci" 

" Lib_System.mcl" " Lib_Delays .mci" " Lib_LcdConsts .mci" 

" LibLcd.mcl": Specify input files. 
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PROJECTS 

The mikroC PRO for PIC organizes applications into projects, consisting of a single 
project file (extension .mcppi) and one or more source files (extension ). mikroC 
PRO for PIC IDE allows you to manage multiple projects (see Project Manager). 
Source files can be compiled only if they are part of a project. 

The project file contains the following information: 

- project name and optional description, 

- target device, 

- device flags (config word), 

- device clock, 

- list of the project source files with paths, 

- header files (*.h), 

- binary files (*.mcl), 

- image files, 

- other files. 

Note that the project does not include files in the same way as preprocessor does, 
see Add/Remove Files from Project. 

New Project 

The easiest way to create a project is by means of the New Project Wizard, drop- 
down menu Project > New Project or by clicking the New Project Icon a 
from Project Toolbar. 
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New Project Wizard Steps 



Start creating your New project, by clicking Next button: 



New Project Wizard 







Welcome to the New Project 
Wizard 

This wizard helps you: 

• Create a new project 

• Select the device for your project 

• Setup device clock and choose device flags 

• Select desired memory model 

• Add project files 



Click Next to continue 



Cancel 



Step One - Select the device from the device drop-down list. 



New Project Wizard 



Step 1/5 



Select the device you want to use. 



L 



♦ Back 



Next ♦ 



► 



Cancel 
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Step Two - Enter the oscillator frequency value. 




New Project Wizard 


@ 


Step 2/5 ! 


'setup the clock, for example 11.0592 MHz, 






Device Clock:| 11.059200| MHz 




<> Back Next <$ 


Cancel 





Step Three - Specify the location where your project will be saved. 



New Project Wizard 

Specify where your project will be saved. 
Project File Name: 






♦ Back Next 



±J 
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Step Four - Add project file to the project if they are avaiable at this point. You can 
always add project files later using Project Manager. 



New Project Wizard 



Step 4/5 



Add project files if they are available at this point, 

You can always add project files later using the Project Manager in IDE. 

Add File To Project: 

D:\Projects\FirstProject\Definit, h 



File Name 

D : \Projects\FirstProject\Def init . h 



^ Back Next + 



1^1 



Add 



Remove 
Remove All 



Cancel 



Step Five - Click Finish button to create your New Project. 



New Project Wizard 



Step 5/5 



You have successfully created a new project. Click Finish to save the changes 
and to close the wizard. 



^> 



Related topics: Project Manager, Project Settings 
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PROJECTS 

The mikroC PRO for PIC organizes applications into projects, consisting of a single 
project file (extension .mcppi) and one or more source files (extension). mikroC 
PRO for PIC IDE allows you to manage multiple projects (see Project Manager). 
Source files can be compiled only if they are part of a project. 

The project file contains the following information: 

- project name and optional description, 

- target device, 

- device flags (config word), 

- device clock, 

- list of the project source files with paths, 

- header files (* .h), 

- binary files (* .mci), 

- image files, 

- other files. 

Note that the project does not include files in the same way as preprocessor does, 
see Add/Remove Files from Project. 

New Project 

The easiest way to create a project is by means of the New Project Wizard, drop- 
down menu Project > New Project or by clicking the New Project Icon t from 
Project Toolbar. 
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New Project Wizard Steps 



Start creating your New project, by clicking Next button: 



New Project Wizard 


^ 




Welcome to the New Project 
Wizard 






This wizard helps you: 




• Create a new project 

• Select the device for your project 

• Setup device clock and choose device flags 

• Select desired memory model 

• Add project files 




Click Next to continue 












Next ^ Cancel 







Step One - Select the device from the device drop-down list. 



New Project Wizard 



Step 1/5 



Select the device you want to use. 



■^ Back Next ♦ 
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Step Two - Enter the oscillator frequency value. 



New Project Wizard 



Step 2/5 



Setup the clock, for example 11.0592 MHz. 



Device Clock:|_ 



11,059200| mHz 



L 



♦ Back Next ♦ 



lJ L 



Cancel 



Step Three - Specify the location where your project will be saved. 



Step 3/5 



New Project Wizard 

Specify where your project will be saved 
Project File Name: 



Back Next ♦ 



Cancel 
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Step Four - Add project file to the project if they are avaiable at this point. You can 
always add project files later using Project Manager. 



New Project Wizard \S3-\ 


Step 4/5 


Add project files if they are available at this point, 

You can always add project files later using the Project Manager in IDE. 


Add File To Project: 


D:\Projects\FirstProject\DeFinit, h & Add 


File Name 




D : \Projects\FirstProject\Def init . h 


Remove 
Remove Al 1 








■^ Back Next + Cancel 





Step Five - Click Finish button to create your New Project: 




You have successfully created a new project. Click Finish to save the changes 
and to close the wizard, 



3> 



> Back 



finish 
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CUSTOMIZING PROJECTS 

Edit Project 

You can change basic project settings in the Project Settings window. You can 
change chip, and oscillator frequency. Any change in the Project Setting Window 
affects currently active project only, so in case more than one project is open, you 
have to ensure that exactly the desired project is set as active one in the Project 
Manager. Also, you can change configuration bits of the selected chip in the Edit 
Project window. 

Managing Project Group 

mikroC PRO for PIC IDE provides covenient option which enables several projects 
to be open simultaneously. If you have several projects being connected in some 
way, you can create a project group. 

The project group may be saved by clicking the Save Project Group Icon 1^ from 

the Project Manager window. The project group may be reopend by clicking the 

Open Project Group Icon ^ . All relevant data about the project group is stored in 

the project group file (extension .mpgroup) 

Add/Remove Files from Project 

The project can contain the following file types: 

- source files 

- .h header files 

- .mci binary files 

- pid project level defines files 

- image files 

- .hex, .asm and . 1st files, see output files. These files can not be added or 
removed from project. 

- other files 
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Project Manager 


© 


IS^jgF 3 * * £T | £f j | \%\fr 


J-jjjV T6963C_240Kl28.mcppi 




i 


■tr^i Sources 

; 1) T6963C_240xl28.t 

= | bitmap. c 




A 


■■■{Q Header Files 
■-fi ™63C.h 




A 


If^l Binaries 

jfij] bitmap2.mcl 
■Ir^l Project level defines 




A 


■Ir^l Image Files 
f| sample, jpg 




A 


■d Output Files 

! jl T6963C_240xl28.hex 

1§| T6963C_240xl28.asm 
pi T6963C 240x128.1st 




J-tO Other File? 




; (J DATA-doc3286.pdf 




1 



The list of relevant source files is stored in the project file (extension .mcppi). 

To add source file to the project, click the Add File to Project Icon f . Each added 

source file must be self-contained, i.e. it must have all necessary definitions after 

preprocessing. 

To remove file(s) from the project, click the Remove File from Project Icon ( ' . 

Project Level Defines: 

Project Level Defines (.pld) files can also be added to project. Project level define 
files enable you to have defines that are visible in all source files in the project. A file 
must contain one definition per line in the following form: 

<symbol>[ =[ <value>] ] 
<symbol (a, b) >[ =[ <value>] ] 

Define a macro named symbol. To specify a value, use =<value>. If =<value> is 
omitted, 1 is assumed. Do not enter white-space characters immediately before the 
" = ". If a white-space character is entered immediately after the " = ", the macro is 
defined as zero token. This option can be specified repeatedly. Each appearance of 
symbol will be replaced by the value before compilation. 
There are two predefined project level defines. See predefined project level defines 

Note: For inclusion of the header files (extension .h), use the preprocessor direc- 
tive #include. See File Inclusion for more information. 

Related topics: Project Manager, Project Settings, Edit Project 
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SOURCE FILES 

Source files containing C code should have the extension . The list of source files 
relevant to the application is stored in project file with extension .mcppi, along with 
other project information. You can compile source files only if they are part of the 
project. 

Use the preprocessor directive # include to include header files with the extension 
.h. Do not rely on the preprocessor to include source files other than headers — 
see Add/Remove Files from Project for more information. 

Managing Source Files 

Creating new source file 

To create a new source file, do the following: 

1 . Select File > New Unit from the drop-down menu, or press Ctrl+N, or click the 

New File Icon j from the File Toolbar. 

2. A new tab will be opened. This is a new source file. Select File > Save from the 
drop-down menu, or press Ctrl+S, or click the Save File Icon jj^j from the File 
Toolbar and name it as you want. 

If you use the New Project Wizard, an empty source file, named after the project with 
extension, will be created automatically. The mikroC PRO for PIC does not require you 
to have a source file named the same as the project, it's just a matter of convenience. 

Opening an existing file 

1 . Select File > Open from the drop-down menu, or press Ctrl+O, or click the Open 
File Icon ^-r from the File Toolbar. In Open Dialog browse to the location of the 
file that you want to open, select it and click the Open button. 

2. The selected file is displayed in its own tab. If the selected file is already open, its 
current Editor tab will become active. 

Printing an open file 

1 . Make sure that the window containing the file that you want to print is active. 

2. Select File > Print from the drop-down menu, or press Ctrl+P. 

3. In the Print Preview Window, set a desired layout of the document and click the 
OK button. The file will be printed on the selected printer. 
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Saving file 

1 . Make sure that the window containing the file that you want to save is active. 

2. Select File > Save from the drop-down menu, or press Ctrl+S, or click the Save 

File Icon ^ from the File Toolbar. 
Saving file under a different name 

1 . Make sure that the window containing the file that you want to save is active. 

2. Select File > Save As from the drop-down menu. The New File Name dialog will 
be displayed. 

3. In the dialog, browse to the folder where you want to save the file. 

4. In the File Name field, modify the name of the file you want to save. 

5. Click the Save button. 

Closing file 

1 . Make sure that the tab containing the file that you want to close is the active tab. 

2. Select File > Close from the drop-down menu, or right click the tab of the file that 
you want to close and select Close option from the context menu. 

3. If the file has been changed since it was last saved, you will be prompted to save 
your changes. 

Related topics:File Menu, File Toolbar, Project Manager, Project Settings, 
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CLEAN PROJECT FOLDER 

This menu gives you option to choose which files from your current project you want 
to delete. 

Files marked in bold can be easily recreated by building a project. Other files should 
be marked for deletion only with a great care, because IDE cannot recover them. 



Clean Project Folder (a) 


Below is the list of all files in the project folder. Files in bold are those 


generated by the compiler and they can be easily recreated when the 


project is rebuilt. 
I 


Select which files you want to remove from the project folder. Please 


note that selected files will be permanently deleted from your disk if 




i-PTl SpiEthernet.asm 


* 


!■■■__ SpiEthernet.c 




l-M SpiEthernet.c. ini 




1— |l 1 SpiEthernet.cp 




\-M SpiEthernet.dbg 




h@ SpiEthernet.dct 




!■■■__ SpiEthernet.dlt 




i-lBl SpiEthernet.heH 




!■__ SpiEthernet.lst 




! -__ SpiEthernet.md 




\-f~\ 5piEthernet . rncppi 




i-IVI 5piEthernet.mcppi_callertable.tKt 




;■■■__ SpiEthernet.mil 




! -|r| SpiEthernet, user, die 


■ 




Clean 




Cancel 


C:\Program Files\Mikroelektronika\mikroC PROforPICX 





Related topics: Customizing Projects 
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COMPILATION 

When you have created the project and written the source code, it's time to compile 
it. Select Project > Build from the drop-down menu, or click the Build Icon A from 
the Project Toolbar. If more more than one project is open you can compile all open 
projects by selecting Project > Build All from the drop-down menu, or click the Build 
All Icon -A from the Project Toolbar. 

Progress bar will appear to inform you about the status of compiling. If there are 
some errors, you will be notified in the Error Window. If no errors are encountered, 
the mikroC PRO for PIC will generate output files. 

Output Files 

Upon successful compilation, the mikroC PRO for PIC will generate output files in 
the project folder (folder which contains the project file .mcppi). Output files are 
summarized in the table below: 



Format 


Description 


File Type 


Intel HEX 


Intel style hex records. Use this file to program 
PIC MCU. 


. hex 


Binary 


mikro Compiled Library. Binary distribution of 
application that can be included in other projects. 


. mcl 


List File 


Overview of PIC memory allotment: instruction 
addresses, registers, routines and labels. 


.1st 


Assembler File 


Human readable assembly with symbolic names, 
extracted from the List File. 


. asm 



Assembly View 

After compiling the program in the mikroC PRO for PIC, you can click the View 
Assembly icon ^jj or select Project > View Assembly from the drop-down menu 
to review the generated assembly code (.asm file) in a new tab window. Assembly 
is human-readable with symbolic names. 



Related topics: Project Menu, Project Toolbar, Error Window, Project Manager, Pro- 
ject Settings 
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ERROR MESSAGES 



Compiler Error Messages: 



- Syntax error: Expected [ %s] but [ %s] found 

- Array element cannot be function 

- Function cannot return array 

- Inconsistent storage class 

- Inconsistent type 

- [ %s] tag redefined [ %s] 

- Illegal typecast [ %s] [ %s] 

- "%s" is not valid identifier 

- Invalid statement 

- Constant expression required 

- Internal error [ %s] 

■ Too many actual parameters 

- Not enough parameters. 

- Invalid expression 

- Identifier expected, but[ %s] found 

- Operator [ %s] is not applicable to these operands 
■Assigning to non-lvalue [ %s] 

- Cannot cast [ s] to [ %s] 

- Cannot assign [ %s] to [ %s] 

■ Lvalue required 

- Pointer required 

■ Argument is out of range 

■ Undeclared identifier [ %s] in expression 

■ Too many initializers 

- Cannot establish this baud rate at [ is] MHz clock 

■ Stack overflow 

■ Invalid operator! %s] 

■ Expected variable, but constant [ %s] found 

- Expected constant, but[ %s] found 

■ [ %s] cannot be used outside a loop 

■ Unknown type [ %s] 
■Variable! is] is redeclared 

- Undeclared identifier! %s] 

■ Output limit has raised 2K words 

- [ %s] has already been declared [ %s] 

■ Type mismatch: expected [ %s] , but[ %s] found 

- File [ %s] not found [ %s] 

■ There is not enough RAM space for all variables 

■ There is not enough ROM space 

■ Invalid type in Array 

- Division by zero 

■ Incompatible types: [ %s] [ %s] 

■ Too many characters 
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-Assembler instruction [ %s] was not found 

- Project name must be specified 

- Unknown command line Option: [ %s] 

- File extension missing: [ %s] 

- Bad FO argument: [ %s] 

- Preprocessor exited with error code [ %s] 

- Bad absolute address [ %s] 

- Recursion or cross-calling of [ %s] 

- Reentrancy is not allowed: function[ %s] called from two threads 

- no files specified 

- Device parameter missing (for example -P16F..) 

- Invalid parameter string 

- Project name must be set 

- Specifier needed 

- [ %s] not found [ %s] 

- Index out of bounds 

- Array dimension must be greater than 

- Const expression expected 

- Integer const expected 

- Recursion in definition 

- Array corrupted 

- Arguments cannot be of void type 

-Arguments cannot have explicit memory specificator 

- Bad storage class 

- Pointer to function required 

- Function required 

- Illegal pointer conversion to double 

- Integer type needed 

- Members cannot have memory specifier 

- Members cannot be of bit or sbit type 

- Too many initializers 

- Too many initializers of subaggregate 
-Already used [ %s] 

- Illegal expression with void 

- Address must be greater than 

- [ %s] Identifier redefined 

- User abort 

- Expression must be greater than 

- Invalid declarator expected " c or identifier 

- typdef name redefined: [ %s] 

- Declarator error 

- Specifer/qualifier list expected 

- [ %s] already used 

- ILevel can be used only with interrupt service routines 

- ; expected, but[ is] found 

MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 89 



CHAPTER 2 

Environment 



mikroC PRO for PIC 



Expected "{ " 

[ %s] Identifier redefined 

C expected, but [ %s] found 

) " expected, but[ %s] found 

case" out of switch 

:" expected, but [ %s] found 

default" label out of switch 
switch expression must evaluate to integral type 
while expected, but [ is] found 
void func cannot return values 

"continue" Outside Of loop 

Unreachable code 
Label redefined 
void type in expression 
Too many chars 
Unresolved type 

Arrays of objects containing zero-size arrays are illegal 
Invalid enumerator 

ILevel can be used only with interrupt service routines 
ILevel value must be integral constant 
ILevel out of range "0 . . 4 " 
"} " expected | is] found 
") " expected, but[ %s] found 
"break" outside of loop or switch 
Empty char 
Nonexistent field [ %s] 
Illegal char representation: [ %s] 

Initializer syntax error: multidimensional array missing subscript 
Too many initializers of subaggregate 
At least one Search Path must be specified 
Not enough RAM for call stack 
Demo Limit 

Parameter [ is] must not be of bit or sbit type 
Function must not have return value of bit or sbit type 
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Compiler Warning Messages: 

- Bad or missing fosc parameter. Default value 8MHz used 

- Specified search path does not exist: [ %s] 

- Specified include path does not exist: [ %s] 

- Result is not defined in function: [ %s] 

- Initialization of extern object [ %s] 

- Suspicious pointer conversion 

- Implicit conversion of pointer to int 

- Unknown pragma line ignored: [ %s] 

- Implicit conversion of int to ptr 

- Generated baud rate is [ %s] bps (error = [ %s] percent) 

- Unknown memory model [ is] , small memory model used instead 

- IRP bit must be set manually for indirect access to i si variable 

- Variable [ %s] has been declared, but not used' 

- Illegal file type: [ %s] 



Linker Error Messages: 

- Redefinition of [ s] already defined in [ %s] 

- main function is not defined 

- System routine is not found for initialization of: [ %s] 

- Bad aggregate definition [ %s] 

- Unresolved extern | %s] 

- Bad function absolute address [ %s] 

- Not enough RAM [ %s] 
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SOFTWARE SIMULATOR OVERVIEW 



The Source-level Software Simulator is an integral component of the mikroC PRO 
for PIC environment. It is designed to simulate operations of the PIC MCUs and 
assist the users in debugging C code written for these devices. 
Upon completion of writing your program, choose Release build Type in the Project 
Settings window: 



Choose Release type 
if you want to use 
software simulator 



Project Settings 
B<|& Device 




Name: P16F877A 



:- ^Oscillator 



El Build/ Debugger Type 

Build Type 
►■(#) Release 



Value: 



B, 000000 



MHz 



Debugger 
(*) Software 



ICD Debug 



nnikroICD 



After you have successfuly compiled your project, you can run the Software Simu- 
lator by selecting Run > Start Debugger from the drop-down menu, or by clicking 
the Start Debugger Icon j& from the Debugger Toolbar. Starting the Software Sim- 
ulator makes more options available: Step Into, Step Over, Step Out, Run to Cursor, 
etc. Line that is to be executed is color highlighted (blue by default). 

Note: The Software Simulator simulates the program flow and execution of instruc- 
tion lines, but it cannot fully emulate PIC device behavior, i.e. it doesn't update 
timers, interrupt flags, etc. 
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Breakpoints Window 

The Breakpoints window manages the list of currently set breakpoints in the project. 
Doubleclicking the desired breakpoint will cause cursor to navigate to the correspon- 
ding location in source code. 



Breakpoints 



u 



Line 


File Name 


50 


Lcd.c 


54 


Lcd.c 


58 


Lcd.c 


64 


Lcd.c 


75 


Lcd.c 


76 


Lcd.c 



Watch Window 

The Software Simulator Watch Window is the main Software Simulator window 
which allows you to monitor program items while simulating your program. To show 
the Watch Window, select View > Debug Windows > Watch from the drop-down 
menu. 

The Watch Window displays variables and registers of the MCU, along with their 
addresses and values. 

There are two ways of adding variable/register to the watch list: 

■ by its real name (variable's name in "C" code). Just select desired variable/reg- 
ister from Select variable from list drop-down menu and click the Add Button 

4> Add 

■ by its name ID (assembly variable name). Simply type name ID of they 

variable/register you want to display into Search the variable by assemby 
name box and click the Add Button X ^dd ■ 
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Variables can also be removed from the Watch window, just select the variable that 
you want to remove and then click the Remove Button j# R emove ■ 

Add All Button la Add All adds all variables. 

Remove All Button ^ Remove All removes all variables. 

You can also expand/collapse complex variables, i.e. struct type variables, strings... 
Values are updated as you go through the simulation. Recently changed items are 
colored red. 



Watch Values 



! % a a *" *.. 

*•* Add jp( Remo 


re 




1 e 

3 rope 


1 

"ties 




1* 

Add All 


- 


Rem 


ove All 


Select variable from list: 


r 


















' 



Search for variable by assembly name: 
FARG_T6963C_circle+4 

] Peripherals Freeze 

Name 
pic 
panel 

T6963C_dataPort 
T6963C_cntlrst 
T6963C_grWidth 
start 
mode 




Address 








0x0039 
0x0031 
0x0080 
0x0094 
0x0020 
0x004E 
0X003A 
0x0033 



PC= 0X0009FB Cyde= 560.00 



Double clicking a variable or clicking the Properties Button v Properties opens 
the Edit Value window in which you can assign a new value to the selected 
variable/register. Also, you can choose the format of variable/register representation 
between decimal, hexadecimal, binary, float or character. All representations except 
float are unsigned by default. For signed representation click the check box next to 
the Signed label. 
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An item's value can be also changed by double clicking item's value field and typing 
the new value directly. 



[fl Edit Value: ACD 



l inn 1^1 



Representation 

© Dec © Hex 

1^1 Signed 



0100 0000 1000 0011 0001 0010 0110 1111 



'i») Bin 



Float O Char 



OK 



Cancel 



View RAM Window 

Debugger View RAM Window is available from the drop-down menu, View > Debug 
Windows > View RAM. 

The View RAM Window displays the map of PIC's RAM, with recently changed 
items colored red. 



RAM 


History 








00 


01 


02 


03 


04 


05 


06 


07 


08 


09 


OA 


OB 


OC 


0D 


0E 


OF 


ASCII 


D 


0000 


00 


oc 


96 


OC 


00 


00 


3F 


00 


00 


00 


00 


00 


00 


00 


D9 


22 




0010 


00 


00 


00 


DF 


00 


10 


A0 


00 


00 


00 


00 


CO 


A0 


00 


00 


OF 




0020 


00 


00 


04 


00 


00 


E0 


80 


00 


OC 


84 


81 


00 


01 


08 


20 


00 




0030 


11 


00 


25 


00 


49 


08 


00 


40 


04 


00 


44 


10 


00 


10 


00 


00 




0040 


00 


84 


20 


00 


12 


80 


00 


22 


00 


10 


00 


01 


80 


04 


00 


48 




0050 


00 


00 


00 


04 


00 


00 


20 


80 


01 


00 


00 


00 


02 


00 


01 


00 




0060 


4C 


06 


20 


00 


08 


02 


00 


08 


08 


14 


01 


19 


00 


10 


00 


A0 




0070 


00 


08 


15 


60 


06 


00 


01 


08 


10 


01 


21 


66 


26 


50 


00 


00 




0080 


00 


FF 


96 


OC 


00 


3F 


7F 


FF 


FF 


07 


00 


00 


00 


00 


00 


00 




0090 


00 


00 


FF 


00 


00 


00 


00 


00 


02 


00 


00 


00 


07 


00 


00 


00 




00A0 


SO 


01 


84 


00 


40 


20 


03 


00 


00 


04 


00 


18 


00 


41 


20 


00 


„, 


00B0 


08 


00 


01 


10 


02 


00 


00 


00 


00 


00 


04 


40 


02 


28 


24 


82 




ooco 


00 


22 


01 


11 


06 


70 


11 


58 


84 


00 


02 


10 


00 


80 


28 


80 




00D0 


00 


00 


01 


oo 


10 


00 


10 


10 


41 


04 


00 


00 


00 


01 


40 


84 




00E0 


00 


00 


04 


20 


50 


20 


00 


90 


00 


40 


40 


84 


21 


14 


80 


28 




00F0 


00 


08 


15 


60 


06 


00 


01 


08 


10 


01 


21 


66 


26 


50 


00 


00 
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Stopwatch Window 

The Software Simulator Stopwatch Window is available from the drop-down menu, 
View > Debug Windows > Stopwatch. 

The Stopwatch Window displays a current count of cycles/time since the last Soft- 
ware Simulator action. Stopwatch measures the execution time (number of cycles) 
from the moment Software Simulator has started and can be reset at any time. Delta 
represents the number of cycles between the lines where Software Simulator action 
has started and ended. 



Note: The user can change the clock in the Stopwatch Window, which will recalcu- 
late values for the latest specified frequency. Changing the clock in the Stopwatch 
Window does not affect actual project settings - it only provides a simulation. 



Stopwatch 








H 


Current Count: 
Delta: 


Cycles: 




Time: 




3 




9,60 us 










2 




2.40 us 





Stopwatch: 



9.60 us 



Reset To Zero 
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SOFTWARE SIMULATOR OPTIONS 



Name 


Description 


Function 
Key 


Toolbar 
Icon 


Start 
Debugger 


Start Software Simulator. 


[F9] 


jgt, 


Run/Pause 
Debugger 


Run or pause Software Simulator. 


[F6] 


IS] 


Stop 
Debugger 


Stop Software Simulator. 


[Ctrl+F2] 




=5l 


Toggle 
Breakpoints 


Toggle breakpoint at the current cursor 
position. To view all breakpoints, select Run 
> View Breakpoints from the drop-down 
menu. Double clicking an item in the Break- 
points Window List locates the breakpoint. 


[F5] 




a 


Run to cur- 
sor 


Execute all instructions between the current 
instruction and cursor position. 


[F4] 


< 


Step Into 


Execute the current C (single or multi-cycle) 
instruction, then halt. If the instruction is a rou- 
tine call, enter the routine and halt at the first 
instruction following the call. 


[F7] 




C-o 




Step Over 


Execute the current C (single or 
multi-cycle) instruction, then halt. 


[F8] 




gfr 


Step Out 


Execute all remaining instructions in the 
current routine, return and then halt. 


[Ctrl+F8] 







Related topics: Run Menu, Debug Toolbar 
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CREATING NEW LIBRARY 

mikroC PRO for PIC allows you to create your own libraries. In order to create a 
library in mikroC PRO for PIC follow the steps bellow: 

1. Create a new C source file, see Managing Source Files 

2. Save the file in one of the subfolders of the compiler's Uses folder: 

DriveName :\ Program Files\Mikroelektronika\mikroC PRO for 

PIC\Uses\P16\ 

DriveName :\ Program Files\Mikroelektronika\mikroC PRO for 

PIC\Uses\P18\ 

If you are creating library for PIC1 6 MCU family the file should be saved in P1 6 folder. 
If you are creating library for PIC1 8 MCU family the file should be saved in P1 8 fodler. 
If you are creating library for PIC1 6 and PIC1 8 MCU families the file should be 
saved in both folders. 

3. Write a code for your library and save it. 

4. Add Lib Example file in some project, see Project Manager. Recompile the 

project. 

If you wish to use this library for all MCUs, then you should go to Tools > Options 

> Output settings, and check Build all files as library box. 

This will build libraries in a common form which will work with all MCUs. If this 

box is not checked, then library will be built for selected MCU. 

Bear in mind that compiler will report an error if a library built for specific MCU is 

used for another one. 

5. Compiled file LibExample.mcl Should appear in ...\mikroC PRO for 

pic\uses\ folder. 

6. Open the definition file for the MCU that you want to use. This file is placed in the 

compiler's Defs folder: 

DriveName :\ Program Files\Mikroelektronika\mikroC PRO for 
PIC\Defs\ 

and it is named MCU_NAME.mlk, for example 16F887 .mlk 

7. Add the the following segment of code to <libraries> node of the definition 

file (definition file is in XML format): 

<LIB> 
<ALIAS>Example_Library</ALIAS> 

<FILE> Lib_Example</FILE> 

<TYPE>REGULAR</TYPE> 
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</LIB> 

8. Add Library to mlk file for each MCU that you want to use with your library. 

9. Click Refresh button in Library Manager 

10. Example Library should appear in the Library manager window. 

Multiple Library Versions 

Library Alias represents unique name that is linked to corresponding Library .mci 
file. For example UART library for 1 6F887 is different from UART library for 1 8F4520 
MCU. Therefore, two different UART Library versions were made, see mlk files for 
these two MCUs. Note that these two libraries have the same Library Alias (UART) 
in both mlk files. This approach enables you to have identical representation of 
UART library for both MCUs in Library Manager. 

Related topics: Library Manager, Project Manager, Managing Source Files 
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MIKROICD (IN-CIRCUIT 
DEBUGGER) 



mikrolCD is highly effective tool for Real-Time debugging on hardware level. ICD 
debugger enables you to execute a mikroC PRO for PIC program on a host PIC 
microcontroller and view variable values, Special Function Registers (SFR), memo- 
ry and EEPROM as the program is running. 
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Step No. 1 

If you have appropriate hardware and software for using mikrolCD, then, upon com- 
pletion of writing your program, you will have to choose ICD Debug build type. 




Value: 



B Build/ Debugger Type 
Build Type 



_.■ Release 

Debugger 
; Software 



a ICD Debug ■<- 



a mikrolCD 



Choose ICD Debug 
type if you want 
to use mikrolCD 
debug. 



Step No. 2 

You can run the mikrolCD by selecting Run > Debug from the drop-down menu, or 
by clicking Debug Icon Wh . Starting the Debugger makes more options available: 
Step Into, Step Over, Run to Cursor, etc. Line that is to be executed is color high- 
lighted (blue by default). There is also notification about program execution and it 
can be found on Watch Window (yellow status bar). Note that some functions take 
time to execute, so running of program is indicated on Watch Window. 
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EjD void main ( ) { 

TRISB = 0; 
ANSEL = 0; 
ANSELH = 0; 

Lcd_Init ( ) ; 
Lcd_CllKi(LCD_CLEAR) ; 
Lccl_Cmci (LCD_CURSOR_OFF) ; 



17; 1++J { 
r text [ i-1] J ; 





Watch Value: 


a 


1 S& lb lijj | 0" *.. "0 M I a g \ | 4* 

• «j» Add Jf Remove \^> Properties l,--^, Add All * — RemoveAll 


Select variable from list: 


text 


' 



Search for variable by assembly name: 




Name 
PORTB 
TRI5B 
ANSEL 
ANSELH 

O text 



Value 



127 

255 

63 

{...} 



Address 
0x0006 
0x0086 
0x0188 
0x0189 
0x0020 



PC= OxOOOOAF Cycle = 0,00 
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mikrolCD Debugger Options 



Name 


Description 


Function Key 


Debug 


Start Debugger. 


[F9] 


Run/Pause 
Debugger 


Run or pause Debugger. 


[F6] 


Toggle 
Breakpoints 


Toggle breakpoint at the current cursor posi- 
tion. To view all breakpoints, select Run > 
View Breakpoints from the drop-down menu. 
Double clicking an item in the Breakpoints 
Window List locates the breakpoint. 


[F5] 


Run to cursor 


Execute all instructions between the current 
instruction and cursor position. 


[F4] 


Step Into 


Execute the current C (single or multi-cycle) 
instruction, then halt. If the instruction is a routine 
call, enter the routine and halt at the first instruc- 
tion following the call. 


[F7] 


Step Over 


Execute the current C (single or multi-cycle) 
instruction, then halt. If the instruction is a rou- 
tine call, skip it and halt at the first instruction 
following the call. 


[F8] 


Flush RAM 


Flush current PIC RAM. All variable values 
will be changed according to values from 
watch window. 


N/A 


Disassembly 
View 


Toggle between disassembly and C source 
view. 


[Alt+D] 
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mikrolCD Debugger Examples 

Here is a step by step mikrolCD Debugger Example. 

Step No.1 

First you have to write a program. We will show how mikrolCD works using this 
example: 

// LCD module connections 

sbit LCD_RS at RB4_bit; 

sbit LCD_EN at RB5_bit; 

sbit LCD_D4 at RBOJoit; 

sbit LCD_D5 at RBlJoit; 

sbit LCD_D6 at RB2_bit; 

sbit LCD_D7 at RB3_bit; 

sbit LCD_RS_Direction at TRISB4_bit; 

sbit LCD_EN_Direction at TRISB5_bit; 

sbit LCD_D4_Direction at TRISBOJoit; 

sbit LCD_D5_Direction at TRISBlJoit; 

sbit LCD_D6_Direction at TRISB2_bit; 

sbit LCD_D7_Direction at TRISB3_bit; 
// End LCD module connections 

char text[ 17] = "mikroElektronika" ; 
char i; 

void main ( ) { 
PORTB = 0; 
TRISB = 0; 
ANSEL = ; 
ANSELH = 0; 

Lcd_Init () ; 

Lcd_Cmd (_LCD_CLEAR) ; 

Lcd_Cmd (_LCD_CURSOR_OFF) ; 

for(i = 1; i < 17; i++) { 
Led Chr(l, i, text[ i-1] ); 
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Step No. 2 

After successful compilation and PIC programming press F9 for starting mikrolCD. 
After mikrolCD initialization blue active line should appear: 



THISE = 0; 
ANSEL = 0; 
ANSELH = 0; 

Lcd_Init ( ) ; 
Lccl_CnKl(LCD_CLEAR) ; 
Lcd_Cmd(LCD_CUKSOR_OFF) ; 

lor [1=1; 1 < 17; i++) < 
Led Chr(l, i, text[i-lT); 




Watch Value: 

^j» Add j( Remove \^> Properties '.-,£. Add All 
Select van-able from list; 




Search for variable by 
Jext 
F71 Peripherals Freeze 



Name 


Value 


Address 


PORTB 





0x0006 


THISB 


127 


0x0086 


ANSEL 


255 


0x0188 



ANSELH 
© text 



{,„} 



0x0189 
0x0020 



PC= tlxODOOAF Cvcle= 0.00 



Step No. 3 

We will debug program line by line. Pressing F8 we are executing code line by line. 
It is recommended that user does not use Step Into [F7] and Step Over [F8] over 
Delays routines and routines containing delays. Instead use Run to cursor [F4] and 
Breakpoints functions. 

All changes are read from PIC and loaded into Watch Window. Note that PORTB, 
TRISB, ANSEL and ANSELH changed its values. 255 to 0. 



• 30 



THISE = 0; 
ANSEL = 0; 
ANSELH = 0; 

Lcd_Init ( ) ; 
Lcci_Cmci(LCD_CLEAE) ; 
Lcd_Cmd(LCD_CUKSOR_OFF) ; 

lord = 1; 1 < 17; i++) { 
Led Chr[l, i, text[i-l] ) ; 




Watch Values 






: m a a [ *<> *.. "o oi i = n 1, i > 

J^ Add K Remove ^ Properties l-,j. Add All 


' .„ RemoveAll 




Select variable from list: 


text 




■r 



Search for variable by assembly name: 
text 




Name Value 

PORTB 

TRISB 

ANSEL 

ANSELL 
l±l text 



TRISB 


127 


0x0086 


ANSEL 


255 


0x0188 


ANSELH 


63 


0x0189 



Address 
0X0006 
0x0086 
0x0188 
0x0189 
0x0020 



PC= CxODlMAF 
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Step No. 4 



Step Into [F7] and Step Over [F8] are mikrolCD debugger functions that are used 
in stepping mode. There is also Real-Time mode supported by mikrolCD. Functions 
that are used in Real-Time mode are Run/ Pause Debugger [F6] and Run to cursor 
[F4]. Pressing F4 goes to line selected by user. User just have to select line with 
cursor and press F4, and code will be executed until selected line is reached. 



^void maiii[) { 
POETB = 0; 
TEISE = 0; 
ANSEL = 0; 
ANSELH = 0; 



Lcd_Cmd(LCD_CLEAE) ; 

Led Cmd(LCD CUESOE OFF); 



lor (i = 1; 1 < 17; i++) { 
Lcd_Chr(l, i, text[i-l]); 



Watch Value: 




B 


1 linfij ifij *» *t> •» SI | a g\ | ^1 
^ Add K Remove \^> Properties ►.,£ Add All 


' „ Remove All 




Select variable from list 


text 




» 




Search for variable by 
text 



IVl Peripherals Freeze 




Name 

PORTB 
TRISB 
ANSEL 
ANSELH 

text 









128 


0x0006 


64 


0x0086 





0x0188 





0x0189 




{...} 


0x0020 





PC= Gx0(i(m)['3 



Step No. 5 



Run(Pause) Debugger [F6] and Toggle Breakpoints [F5] are mikrolCD debugger functions 
that are used in Real-Time mode. Pressing F5 marks line selected by user for breakpoint. 
F6 executes code until breakpoint is reached. After reaching breakpoint Debugger halts. 
Here at our example we will use breakpoints for writing "mikroElektronika" on Led char by 
char. Breakpoint is set on Lcd_Chr and program will stop everytime this function is reached. 
After reaching breakpoint we must press F6 again for continuing program execution. 



n void main ( ) { 

POETB = 0; 

TEISB = 0; 

ANSEL = 0; 

ANSELH = 0; 

Lcd_Init ( ) ; 

Led CmdlLCD CLEAE) ; 








A & IS *" *n M«|Bl4|* 
^ Add X : nove \^> Properties t-jjL Add All IjgsL Remove All 


Select variable from list: 



Search for variable by 
Jext 




|Vl Peripherals Freeze 



Name 


Value 


PORTB 


129 


TRISB 


64 


ANSEL 





ANSELH 





ffl text 


{...} 




Address 
OX0006 
0x0086 
0x0188 
0x0189 
0x0020 
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Breakpoints has been separated into two groups. There are hardware and software 
break points. Hardware breakpoints are placed in PIC and they provide fastest 
debug. Number of hardware breakpoints is limited (1 for P16 and 1 or 3 for P18). If 
all hardware brekpoints are used, next breakpoints that will be used are software 
breakpoint. Those breakpoints are placed inside mikrolCD, and they simulate hard- 
ware breakpoints. Software breakpoints are much slower than hardware break- 
points. This differences between hardware and software differences are not visible 
in mikrolCD software but their different timings are quite notable, so it is important 
to know that there is two types of breakpoints. 
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mikrolCD (In-Circuit Debugger) Overview 

Breakpoints Window 

The Breakpoints window manages the list of currently set breakpoints in the project. 
Doubleclicking the desired breakpoint will cause cursor to navigate to the correspon- 
ding location in source code. 



Breakpoints 


H 


Line File Name 


50 Lcd.c 




54 Lcd.c 




58 Lcd.c 




64 Lcd.c 




75 Lcd.c 




76 Lcd.c 
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Watch Window 

Debugger Watch Window is the main Debugger window which allows you to moni- 
tor program items while running your program. To show the Watch Window, select 
View > Debug Windows > Watch Window from the drop-down menu. 

The Watch Window displays variables and registers of PIC, with their addresses and 
values. Values are updated as you go through the simulation. Use the drop-down 
menu to add and remove the items that you want to monitor. Recently changed 
items are colored red. 
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^ Add X Remove \£j Properties Oufi. Add All 


\-„ RemoveAll 




Select variable from list: 




! 


t 



Search for variable by assembly name 
ADRESH 



i/\ Peripherals Freeze 




Name 


Value 


Address 


CCP1C0N 





0x0017 


CVRCON 





0x009D 


EEADR 


58 


OxOlOD 


EEDATA 


255 


OxOlOC 


FSR 





0x0004 


INTCON 





OxOOOB 


PCL 


150 


0x0002 


PCLATH 





OxOOOA 


5SPC0N 





0x0014 


55PBUF 


223 


0x0013 


TXREG 





0x0019 


TMR2 





0x0011 


ADCONO 


OxOF 


0x00 IF 


ADC0N1 





0x009F 






PC= 0x000005 



Cvcle= 0.00 
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Double clicking an item opens the Edit Value window in which you can assign a new 
value to the selected variable/register. Also, you can change view to binary, hex, 
char, or decimal for the selected item. 



H Edit Value: ACD 






^^^ 




oioooooo looooouoooi ooioouo mi J 


n i- ■-■ 






O Dec O Hex 


® Bin O Float © Char 




Signed 










OK 


Cancel 











EEPROM Watch Window 



mikrolCD EEPROM Watch Window is available from the drop-down menu, View > 
Debug Windows > View EEPROM. 

The EEPROM Watch window shows current values written into PIC internal 
EEPROM memory. There are two action buttons concerning EEPROM Watch win- 
dow - Write EEPROM and Read EEPROM. Write EEPROM writes data from 
EEPROM Watch window into PIC internal EEPROM memory. Read EEPROM reads 
data from PIC internal EEPROM memory and loads it up in EEPROM window. 
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Code Watch Window 



mikrolCD Code Watch Window is available from the drop-down menu, View > 
Debug Windows > View Code. 

The Code Watch window shows code (hex code) written into PIC. There is action 
button concerning Code Watch window - Read Code. Read Code reads code from 
PIC and loads it up in View Code Window. 
Also, you can set an address scope in which hex code will be read. 



CODE Watch 
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View RAM Memory 

Debugger View RAM Window is available from the drop-down menu, View > Debug 
Windows > View RAM. 

The View RAM Window displays the map of PIC's RAM, with recently changed 
items colored red. 
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Common Errors 

■ Trying to program PIC while mikrolCD is active. 

■ Trying to debug Release build Type version of program. 

■ Trying to debug changed program code which hasn't been compiled and pro 
grammed into PIC. 

■ Trying to select line that is empty for Run to cursor [F4] and Toggle Breakpoints 
[F5] functions. 

■ Trying to debug PIC with mikrolCD while Watch Dog Timer is enabled. 

■ Trying to debug PIC with mikrolCD while Power Up Timer is enabled. 

■ It is not possible to force Code Protect while trying to debug PIC with mikrolCD. 

■ Trying to debug PIC with mikrolCD with pull-up resistors set to ON on RB6 and RB7. 

■ For correct mikrolCD debugging do not use pull-ups. 
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MIKROICD ADVANCED BREAKPOINTS 

mikrolCD provides the possibility to use the Advanced Breakpoints. Advanced 
Breakpoints can be used with PIC18 and PIC18FJ MCUs. To enable Advanced 
Breakpoints set the Advanced Breakpoints checkbox inside Watch window: 



[V] Advanced Breakpoints 

To configure Advanced Breakpoints, start mikrolCD [F9] and select View > Debug 
Windows > Advanced Breakpoints option from the drop-down menu or use 
[Ctrl+Shift+A] shortcut. 



[^ Advanced Breakpoints 

Breakpoint #1 

[yl Program Memory Break 
Address 0200 

□ File Register Break 

® Read Access 
Write Access 



Breakpoint #2 

O Program Memory Break 
Address loOOO 



Breakpoint #3 

I I Program Memory Break 
Address loOOO 



F71 File Register Break 
Address 



000 



o Read Access 
O Write Access 



| | File Register Break 
Address 



QFile Register Equal 
Value [00~ 



Passcount 1 

Emulator Features 
Event Breakpoints 

I | Break on Stack Over/Underflow 
I I Break on Watchdog Timer 
[7] Break on SLEEP 



0FS 

File Register Equal 

Value 9 

Passcount 2 



Ca) Read Access 
Write Access 



I I File Register Equal 
Value 1 00 



O 



I I Enable Stopwatch 
I I Halt on Start Condition (Breakpoint 2) 
I I Halt on Stop Condition (Breakpoint 3) 
O Reset Stopwatch on Run 



Apply 



Note: When Advanced Breakpoints are enabled mikrolCD operates in Real-Time 
mode, so it will support only the following set of commands: start Debugger [F9], 
Run/Pause Debugger [F6] and stop Debugger [Ctrl+F2]. Once the Advanced 
Breakpoint is reached, the Advanced Breakpoints feature can be disabled and 
mikrolCD debugging can be continued with full set of commands. If needed, 
Advanced Breakepoints can be re-enabled without restarting mikrolCD. 

Note: Number of Advanced Breakpoints is equal to number of Hardware break- 
points and it depends on used MCU. 
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Program Memory Break 

Program Memory Break is used to set the Advanced Breakpoint to the specific 
address in program memory. Because of PIC pipelining mechanism program exe- 
cution may stop one or two instructions after the address entered in the Address 
field. Value entered in the Address field must be in hex format. 

Note: Program Memory Break can use the Passcount option. The program execu- 
tion will stop when the specified program address is reached for the N-th time, 
where N is the number entered in the Passcount field. When some Advanced 
Breakpoint stops the program execution, passcount counters for all Advanced 
Breakpoints will be cleared. 

Program Memory Break 

Program Memory Break is used to set the Advanced Breakpoint to the specific 
address in program memory. Because of PIC pipelining mechanism program exe- 
cution may stop one or two instructions after the address entered in the Address 
field. Value entered in the Address field must be in hex format. 

Note: Program Memory Break can use the Passcount option. The program execu- 
tion will stop when the specified program address is reached for the N-th time, 
where N is the number entered in the Passcount field. When some Advanced 
Breakpoint stops the program execution, passcount counters for all Advanced 
Breakpoints will be cleared. 

File Register Break 

File Register Break can be used to stop the code execution when read/write access 
to the specific data memory location occurs. If Read Access is selected, the File 
Register Equal option can be used to set the matching value. The program execu- 
tion will be stopped when the value read from the specified data memory location is 
equal to the number written in the value field. Values entered in the Address and 
value fields must be in hex format. 

Note: File Register Break can also use the Passcount option in the same way as 
Program Memory Break. 
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Emulator Features 
Event Breakpoints 

■ Break on Stack Overflow/Underflow: not implemented. 

■ Break on Watchdog Timer: not implemented. 

■ Break on SLEEP: break on SLEEP instruction. SLEEP instruction will not be 
executed. If you choose to continue the mikrolCD debugging [F6] then the pro- 
gram execution will start from the first instruction following the SLEEP instruction. 

Stopwatch 

Stopwatch uses Breakpoint#2 and Breakpoint#3 as a Start and Stop condi- 
tions. To use the Stopwatch define these two Breakpoints and check the Enable 
stopwatch checkbox. 

Stopwatch options: 

Halt on Start Condition 

■ Halt on Start Condition (Breakpoint#2): when checked, the program execution 
will stop on Breakpoint#2. Otherwise, Breakpoint#2 will be used only to 
start the Stopwatch. 

■ Halt on Stop Condition (Breakpoint#3): when checked, the program execution 
will stop on Breakpoint#3. Otherwise, Breakpoint#3 will be used only to 
stop the Stopwatch. 

■ Reset Stopwatch on Run: when checked, the Stopwatch will be cleared before 
continuing program execution and the next counting will start from zero. Other- 
wise, the next counting will start from the previous Stopwatch value 
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mikroC PRO for PIC 
Specifics 

The following topics cover the specifics of mikroC PRO for PIC compiler: 

-ANSI Standard Issues 

- Predefined Globals and Constants 
-Accessing Individual Bits 

- Interrupts 

- PIC Pointers 

- Linker Directives 

- Built-in Routines 

- Code Optimization 

- Memory Type Specifiers 
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ANSI Standard Issues 

Divergence from the ANSI C Standard 

- Tentative declarations are not supported. 

C Language Exstensions 

mikroC PRO for PIC has additional set of keywords that do not belong to the ANSI 
standard C language keywords: 

- code 

- data 

- rx 
-at 
-sbit 

- bit 
-sfr 

Related topics: Keywords, PIC Specific 

Predefined Globals and Constants 

To facilitate programming of PIC compliant MCUs, the mikroC PRO for PIC imple- 
ments a number of predefined globals and constants. 

All PIC SFR registers and their bits are implicitly declared as global variables. 
These identifiers have an external linkage, and are visible in the entire project. 
When creating a project, the mikroC PRO for PIC will include an appropriate (- ) file 
from defs folder, containing declarations of available SFR registers and constants. 

For a complete set of predefined globals and constants, look for "Defs" in the mikroC 
PRO for PIC installation folder, or probe the Code Assistant for specific letters 
(Ctrl+Space in the Code Editor). 
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Predefined project level defines 

There are four predefined project level defines for any project you make. These 
defines are based on values that you have entered/edited in the current project: 

- First one is equal to the name of selected device for the project i.e. if 16F887 is 
selected device, then 16F887 token will be defined as 1, so it can be used for 
conditional compilation: 

#ifdef P16F887 
#endif 

- The second one is FOSC value of frequency (in Khz) for which the project 

is built. 

- Third one is for identifying mikroC PRO for PIC compiler: 

#ifdef MIKROC_PRO_FOR_PIC_ 

#endif 

- Fourth one is for identifying the build version. For instance, if a desired build ver 
sion is 142, user should put this in his code: 

#if MIKROC_PRO_FOR_PIC_BUILD == 142 

#endif 

User can define custom project level defines. 

Accessing Individual Bits 

The mikroC PRO for PIC allows you to access individual bits of 8-bit variables. It 
also supports sbit and bit data types 

Accessing Individual Bits Of Variables 

If you are familiar with a particular MCU, you can access bits by name: 

// Clear Global Interrupt Bit (GIE) 
GIEJoit = 0; 

Also, you can simply use the direct member selector (.) with a variable, followed by 
one of identifiers bo, bi, ... , B7, orFO, fi, ... F7, with F7 being the most sig- 
nificant bit: 

// Clear bit in INTCON register 
INTCON.B0 = 0; 

// Set bit 5 in ADCON0 register 
ADCON0.F5 = 1; 
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There is no need of any special declarations. This kind of selective access is an 
intrinsic feature of mikroC PRO for PIC and can be used anywhere in the code. Iden- 
tifiers bo-b7 are not case sensitive and have a specific namespace. You may over- 
ride them with your own members bo-b7 within any given structure. 

See Predefined Globals and Constants for more information on register/bit names. 

Note: If aiming at portability, avoid this style of accessing individual bits, use the bit 
fields instead. 

sbit type 

The mikroC PRO for PIC compiler has sbit data type which provides access to bit- 
addressable SFRs. You can access them in the following manner: 

sbit LEDA at PORTA. BO; 

sbit bit name at sf r-name . B<bit-position> ; 

sbit LEDB at PORTB.FO; 

sbit bit name at sf r-name . F<bit-position> ; 

// If you are familiar with a particular MCU and its ports and direc- 
tion registers (TRIS) , you can access bits by their names: 
sbit LEDC at RCOJoit; 
sbit bit name at R<port-letter><bit-position>_bit; 

sbit TRISCO at TRISCOJoit; 

sbit bit_name at TRIS<port-letter><bit-position>_bit ; 

bit type 

The mikroC PRO for PIC compiler provides a bit data type that may be used for vari- 
able declarations. It can not be used for argument lists, and function-return values. 

bit bf; // bit variable 

There are no pointers to bit variables: 

bit *ptr; // invalid 

An array of type bit is not valid: 

bit arr [ 5] ; // invalid 
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Note: 

- Bit variables can not be initialized. 

- Bit variables can not be members of structures and unions. 

- Bit variables do not have addresses, therefore unary operator & (address of) is not 
applicable to these variables. 

Related topics: Bit fields, Predefined globals and constants 

Interrupts 

Interrupts can be easily handled by means of reserved word interrupt. mikroC 
PRO for PIC implictly declares function interrupt which cannot be redeclared. Its 
prototype is: 

void interrupt (void) ; 

For P18 low priorty interrupts reserved word is interrupt low: 

void interrupt_low (void) ; 

You are expected to write your own definition (function body) to handle interrupts in 
your application. 

mikroC PRO for PIC saves the following SFR on stack when entering interrupt and 
pops them back upon return: 

- PIC12 family: w, status, fsr, pclath 

- PIC16 family: w, status, fsr, pclath 

- PIC1 8 family: fsr (fast context is used to save wreg, status, bsr) 

Use the ipragma disabiecontexsaving to instruct the compiler not to automatical- 
ly perform context-switching. This means that no regiser will be saved/restored by 
the compiler on entrance/exit from interrupt service routine. This enables the user to 
manually write code for saving registers upon entrance and to restore them before 
exit from interrupt. 
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P18 priority interrupts 

Note: For the P18 family both low and high interrupts are supported. 

1. function with name interrupt will be linked as ISR (interrupt service routine) 
for high level interrupt 

2. function with name interruptiow will be linked as ISR for low level inter 
ruptjow 

If interrupt priority feature is to be used then the user should set the appropriate SFR 
bits to enable it. For more information refer to datasheet for specific device. 

Function Calls from Interrupt 

Calling functions from within the interrupt^) routine is now possible. The compiler 
takes care about the registers being used, both in "interrupt" and in "main" thread, 
and performs "smart" context-switching between the two, saving only the registers 
that have been used in both threads. Check functions reentrancy. 

Interrupt Examples 

Here is a simple example of handling the interrupts from tmro (if no other interrupts 
are allowed): 

void interrupt () { 
counter++; 
TMRO = 96; 
INTCON = $20; 

} 

In case of multiple interrupts enabled, you need to test which of the interrupts 
occurred and then proceed with the appropriate code (interrupt handling): 

void interrupt () { 

if (INTCON. TMROIF) { 

counter++; 

TMRO = 96; 

INTCON. TMROF = 0; 
} 
else if (INTCON. RBIF) { 

counter++; 

TMRO = 96; 

INTCON. RBIF = 0; 
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Linker Directives 

The mikroC PRO uses an internal algorithm to distribute objects within memory. If 
you need to have a variable or routine at specific predefined address, use the link- 
er directives absolute and org. 

Directive absolute 

Directive absolute specifies the starting address in RAM for a variable. If the vari- 
able is multi-byte, higher bytes will be stored at the consecutive locations. 

Directive absolute is appended to declaration of a variable: 

short x absolute 0x22; 

// Variable x will occupy 1 byte at address 0x22 

int y absolute 0x2 3; 

// Variable y will occupy 2 bytes at addresses 0x23 and 0x24 

Be careful when using the absolute directive, as you may overlap two variables by 
accident. For example: 

char i absolute 0x33; 

// Variable i will occupy 1 byte at address 0x33 

long jjjj absolute 0x3 0; 

// Variable will occupy 4 bytes at 0x30, 0x31, 0x32, 0x33; thus, 

// changing i changes jjjj highest byte at the same time, and vice versa 

Directive org 

Directive org specifies a starting address of a routine in ROM. 

Directive org is appended to the function definition. Directives applied to non-defin- 
ing declarations will be ignored, with an appropriate warning issued by the linker. 

Here is a simple example: 

void func (int par) org 0x200 { 
// Function will start at address 0x200 
asm nop; 

} 

It is possible to use org directive with functions that are defined externally (such as 
library functions). Simply add org directive to function declaration: 
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void UART_Writel (char data) org 0x200; 

Note: Directive org can be applied to any routine except for interrupt. 

Directive orgall 

If the user wants to place his routines, constants, etc, above a specified address in 
ROM, #pragma orgaii directive should be used: 

fpragma orgall 0x200 

Directive funcorg 

You can use the #pragma funcorg directive to specify the starting address of a rou- 
tine in ROM using routine name only: 

fpragma funcorg <func name> <starting address> 

Related topics: Indirect Function Calls 

Indirect Function Calls 

If the linker encounters an indirect function call (by a pointer to function), it assumes 
that any of the functions addresses of which were taken anywhere in the program, 
can be called at that point. Use the tpragma funcaii directive to instruct the link- 
er which functions can be called indirectly from the current function: 

fpragma funcall <func name> <called func>[ , <called func>, . . .] 

A corresponding pragma must be placed in the source module where the function 
func name is implemented. This module must also include declarations of all func- 
tions listed in the called_func list. 

These functions will be linked if the function func name is called in the code no mat- 
ter whether any of them was called or not. 

Note: The #pragma funcaii directive can help the linker to optimize function frame 
allocation in the compiled stack. 

Related topics: Linker Directives 
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Built-in Routines 

mikroC PRO for PIC compiler provides a set of useful built-in utility functions. Built-in functions do 
not require any header files to be included; you can use them in any part of your project. 

Built-in routines are implemented as "inline"; i.e. code is generated in the place of the call, so the 
call doesn't count against the nested call limit. The only exceptions are vdeiay ms, Delay eye 
and Get fosc kHz which are actual C routines. 

Note: Lo, Hi, Higher and Highest functions are not implemented in compiler any more. If you 
want to use these functions you must include built in. h into your project. 

- Lo 

- Hi 

- Higher 

- Highest 

- Delay_us 

- Delay_ms 

- Vdelay_ms 

- DelayCyc 

- Clock_Khz 

- Clock_Mhz 

- GetFosckHz 

Lo 



Prototype 


unsigned short Lo (long number); 


Returns 


Returns the lowest 8 bits (byte) of number, bits 0..7. 


Description 


Function returns the lowest byte of number. Function does not interpret bit pat- 
terns of number - it merely returns 8 bits as found in register. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. 


Requires 


Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). 


Example 


d = 0xlAC30F4; 

tmp = Lo(d); // Equals 0xF4 
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Hi 



Prototype 


unsigned short Hi (long number) ; 


Returns 


Returns next to the lowest byte of number, bits 8. .15. 


Description 


Function returns next to the highest byte of number. Function does not interpret 
bit patterns of number - it merely returns 8 bits as found in register. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. 


Requires 


Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). 


Example 


d = 0xlAC30F4; 

tmp = Hi(d); // Equals 0x30 



Higher 



Prototype 


unsigned short Higher (long number); 


Returns 


Returns next to the highest byte of number, bits 16. .23. 


Description 


Function returns the highest byte of number. Function does not interpret bit pat- 
terns of number - it merely returns 8 bits as found in register. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. 


Requires 


Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). 


Example 


d = 0xlAC30F4; 

tmp = Higher (d); // Equals OxAC 
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Highest 



Prototype 


unsigned short Highest (long number) ; 


Returns 


Returns the highest byte of number, bits 24. .31. 


Description 


Function returns next to the highest byte of number. Function does not interpret 
bit patterns of number - it merely returns 8 bits as found in register. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. 


Requires 


Arguments must be variable of scalar type (i.e. Arithmetic Types and Pointers). 


Example 


d = 0xlAC30F4; 

tmp = Highest (d) ; // Equals 0x01 



Delay_us 



Prototype 


void Delay us (const time in us); 


Returns 


Nothing. 


Description 


Creates a software delay in duration of time in us microseconds (a constant). 
Range of applicable constants depends on the oscillator frequency. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. This routine generates nested loops 
using registers R13, R12, rii and rio. The number of used registers varies 
from to 4, depending on requested time in us. 


Requires 


Nothing. 


Example 


Delay us (10) ; /* Ten microseconds pause */ 
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Delay_ms 



Prototype 


void Delay ms (const time in ms); 


Returns 


Nothing. 


Description 


Creates a software delay in duration of time in ms milliseconds (a constant). 
Range of applicable constants depends on the oscillator frequency. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. This routine generates nested loops 
using registers R13, ri2, rii and rio. The number of used registers varies 
from to 4, depending on requested time in ms. 


Requires 


Nothing. 


Example 


Delay ms(lOOO); /* One second pause */ 



Vdelay_ms 



Prototype 


void Vdelay ms (unsigned time in ms); 


Returns 


Nothing. 


Description 


Creates a software delay in duration of time in ms milliseconds (a variable). 
Generated delay is not as precise as the delay created by Delay_ms. 

Note that vdelay ms is library function rather than a built-in routine; it is pre- 
sented in this topic for the sake of convenience. 


Requires 


Nothing. 


Example 


pause = 1000; 

// . .. 

Vdelay ms (pause) ; // ~ one second pause 
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Prototype 


void Delay Cyc (char Cycles div by 10); 


Returns 


Nothing. 


Description 


Creates a delay based on MCU clock. Delay lasts for 10 times the input param- 
eter in MCU cycles. 

Note that Delay cyc is library function rather than a built-in routine; it is pre- 
sented in this topic for the sake of convenience. There are limitations for 
Cycles_div_by_10 value. Value Cycles_div_by_10 must be between 3 and 255. 


Requires 


Nothing. 


Example 


Delay Cyc (10); /* Hundred MCU cycles pause */ 



Clock Khz 



Prototype 


unsigned Clock Khz (void) ; 


Returns 


Device clock in KHz, rounded to the nearest integer. 


Description 


Function returns device clock in KHz, rounded to the nearest integer. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. 


Requires 


Nothing. 


Example 


elk = Clock Khz () ; 
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Clock Mhz 



Prototype 


unsigned short Clock Mhz (void) ; 


Returns 


Device clock in MHz, rounded to the nearest integer. 


Description 


Function returns device clock in MHz, rounded to the nearest integer. 

This is an "inline" routine; code is generated in the place of the call, so the call 
doesn't count against the nested call limit. 


Requires 


Nothing. 


Example 


elk = Clock Mhz () ; 



Get Fosc kHz 



Prototype 


unsigned long Get Fosc kHz (void) ; 


Returns 


Device clock in KHz, rounded to the nearest integer. 


Description 


Function returns device clock in KHz, rounded to the nearest integer. 

Note that Get fosc kHz is library function rather than a built-in routine; it is pre- 
sented in this topic for the sake of convenience. 


Requires 


Nothing. 


Example 


elk = Clock Khz () ; 



Code Optimization 

Optimizer has been added to extend the compiler usability, cut down the amount of code gener- 
ated and speed-up its execution. The main features are: 

Constant folding 

All expressions that can be evaluated in the compile time (i.e. are constant) are being replaced 
by their results. (3 + 5 -> 8); 

Constant propagation 

When a constant value is being assigned to a certain variable, the compiler recognizes this and 
replaces the use of the variable by constant in the code that follows, as long as the value of a vari- 
able remains unchanged. 
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Copy propagation 

The compiler recognizes that two variables have the same value and eliminates one 
of them further in the code. 

Value numbering 

The compiler "recognizes" if two expressions yield the same result and can there- 
fore eliminate the entire computation for one of them. 

"Dead code" elimination 

The code snippets that are not being used elsewhere in the programme do not affect 
the final result of the application. They are automatically removed. 

Stack allocation 

Temporary registers ("Stacks") are being used more rationally, allowing VERY com- 
plex expressions to be evaluated with a minimum stack consumption. 

Local vars optimization 

No local variables are being used if their result does not affect some of the global or 
volatile variables. 

Better code generation and local optimization 

Code generation is more consistent and more attention is payed to implement spe- 
cific solutions for the code "building bricks" that further reduce output code size. 

Related topics: PIC specifics, mikroC PRO for PIC specifics, Memory type specifiers 
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PIC SPECIFICS 



In order to get the most from your mikroC PRO for PIC compiler, you should be 
familiar with certain aspects of PIC MCU. This knowledge is not essential, but it can 
provide you a better understanding of PICs' capabilities and limitations, and their 
impact on the code writing. 
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Types Efficiency 

First of all, you should know that PIC's ALU, which performs arithmetic operations, 
is optimized for working with bytes. Although mikroC PRO for PIC is capable of han- 
dling very complex data types, PIC may choke on them, especially if you are work- 
ing on some of the older models. This can dramatically increase the time needed for 
performing even simple operations. Universal advice is to use the smallest possible 
type in every situation. It applies to all programming in general, and doubly so with 
microcontrollers. 

Get to know your tool. When it comes down to calculus, not all PIC MCUs are of 
equal performance. For example, PIC16 family lacks hardware resources to multi- 
ply two bytes, so it is compensated by a software algorithm. On the other hand, 
PIC18 family has HW multiplier, and as a result, multiplication works considerably 
faster. 

Nested Calls Limitations 

Nested call represents a function call within function body, either to itself (recursive 
calls) or to another function. Recursive function calls are supported by mikroC PRO 
for PIC but with limitations. Recursive function calls can't contain any function 
parameters and local variables due to the PIC's stack and memory limitations. 

mikroC PRO for PIC limits the number of non-recursive nested calls to: 

- 8 calls for PIC1 2 family, 

- 8 calls for PIC1 6 family, 

- 31 calls for PIC1 8 family. 



Note that some of the built-in routines do not count against this limit, due to their 
"inline" implementation. 

Number of the allowed nested calls decreases by one if you use any of the follow- 
ing operators in the code: * / % . It further decreases if you use interrupts in the 
program. Number of decreases is specified by number of functions called from inter- 
rupt. Check functions reentrancy. 

If the allowed number of nested calls is exceeded, the compiler will report a stack 
overflow error. 
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PIC18FxxJxx Specifics 

Shared Address SFRs 

mikroC PRO for PIC does not provide auto setting of bit for acessing alternate reg- 
ister. This is new feature added to pic18fxxjxx family and will be supported in future. 
In several locations in the SFR bank, a single address is used to access two differ- 
ent hardware registers. In these cases, a "legacy" register of the standard PIC18 
SFR set (such as OSCCON, T1CON, etc.) shares its address with an alternate reg- 
ister. These alternate registers are associated with enhanced configuration options 
for peripherals, or with new device features not included in the standard PIC1 8 SFR 
map. A complete list of shared register addresses and the registers associated with 
them is provided in datasheet. 

PIC16 Specifics 

Breaking Through Pages 

In applications targeted at PIC16, no single routine should exceed one page (2,000 
instructions). If routine does not fit within one page, linker will report an error. When 
confront with this problem, maybe you should rethink the design of your application 
- try breaking the particular routine into several chunks, etc. 

Limits of Indirect Approach Through FSR 

Pointers with PIC16 are "near": they carry only the lower 8 bits of the address. Com- 
piler will automatically clear the 9th bit upon startup, so that pointers will refer to 
banks and 1 . To access the objects in banks 2 or 3 via pointer, user should man- 
ually set the IRP, and restore it to zero after the operation. The stated rules apply to 
any indirect approach: arrays, structures and unions assignments, etc. 



Note: It is very important to take care of the IRP properly, if you plan to follow this 
approach. If you find this method to be inappropriate with too many variables, you 
might consider upgrading to PIC18. 

Note: If you have many variables in the code, try rearranging them with the linker 
directive absolute. Variables that are approached only directly should be moved to 
banks 3 and 4 for increased efficiency. 

Related topics: mikroC PRO for PIC specifics 
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MEMORY TYPE SPECIFIERS 

The mikroC PRO for PIC supports usage of all memory areas. Each variable may be explicitly 
assigned to a specific memory space by including a memory type specifier in the declaration, or 
implicitly assigned. 

The following memory type specifiers can be used: 

- code 

- data 

- rx 

-sfr 

Memory type specifiers can be included in variable declaration. 
For example: 

char data data_buf fer; // puts data_buffer in data ram 

const char code txt[ ] = "ENTER PARAMETER:"; // puts text in program memory 



code 






Description 


The code memory type may be used for allocating constants in program memory. 


Example 


// puts txt in program memory 

const char code txt[ ] = "ENTER PARAMETER:"; 



data 



Description 



This memory specifier is used when storing variable to the internal data SRAM. 



Example 



// puts PORTG in data ram 

sfr data unsigned short PORTG absolute 0x65; 



rx 



Description 



This memory specifier allows variable to be stored in the Rx space (Register file). 

Note: In most of the cases, there will be enough space left for the user variables in 
the Rx space. However, since compiler uses Rx space for storing temporary vari- 
ables, it might happen that user variables will be stored in the internal data SRAM, 
when writing complex programs. 



Example 



// puts y in Rx space 
sfr char rx y; 
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sfr 



Description 



Example 



This memory specifier in combination with (rx, data) allows user to access spe- 
cial function registers. It also instructs compiler to maintain same identifier in C and 
assembly. 



sfr rx char y; 



Note: If none of the memory specifiers are used when declaring a variable, data specifier will be 
set as default by the compiler. 

Related topics: Accessing individual bits, SFRs, Constants, Functions 
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Language Reference 



The mikroC PRO for PIC Language Reference describes the syntax, semantics and 
implementation of the mikroC PRO for PIC language. 

The aim of this reference guide is to provide a more understandable description of 
the mikroC PRO for PIC language to the user. 
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- Lexical Elements 

Whitespace 

Comments 

Tokens 

Constants 

Constants Overview 

Integer Constants 

Floating Point Constants 

Character Constants 

String Constants 

Enumeration Constants 

Pointer Constants 

Constant Expression 
Keywords 
Identifiers 
Punctuators 

- Concepts 

Objects and Lvalues 
Scope and Visibility 
Name Spaces 
Duration 

- Types 

Fundamental Types 
Arithmetic Types 
Enumerations 
Void Type 
Derived Types 
Arrays 
Pointers 

Introduction to Pointers 

Pointer Arithmetic 
Structures 

Introduction to Structures 

Working with Structures 

Structure Member Access 

Unions 

Bit Fields 
Type Conversions 

Standard Conversions 
Explicit Typecasting 
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- Declarations 

Introduction to Declarations 

Linkage 

Storage Classes 

Type Qualifiers 

Typedef Specifier 

ASM Declaration 

Initialization 

- Functions 

Introduction to Functions 

Function Calls and Argument Conversion 

- Operators 

Introduction to Operators 

Operators Precedence and Associativity 

Arithmetic Operators 

Relational Operators 

Bitwise Operators 

Logical Opeartors 

Conditional Operators 

Assignment Operators 

Sizeof Operator 

- Expressions 

Introduction to Expressions 
Comma Expressions 

- Statements 

Introduction 
Labeled Statements 
Expression Statements 
Selection Statements 

If Statement 

Switch Statement 
Iteration Statements (Loops) 

While Statement 

Do Statement 

For Statement 
Jump Statements 

Break and Continue Statements 

Goto Statement 

Return Statement 
Compound Statements (Blocks) 
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- Preprocessor 

Introduction to Preprocessor 
Preprocessor Directives 
Macros 
File Inclusion 
Preprocessor Operators 
Conditional Compilation 
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LEXICAL ELEMENTS OVERVIEW 

The following topics provide a formal definition of the mikroC PRO for PIC lexical 
elements. They describe different categories of word-like units (tokens) recognized 
by the mikroC PRO for PIC. 

In the tokenizing phase of compilation, the source code file is parsed (that is, bro- 
ken down) into tokens and whitespace. The tokens in the mikroC PRO for PIC are 
derived from a series of operations performed on your programs by the compiler and 
its built-in preprocessor. 



WHITESPACE 

Whitespace is a collective name given to spaces (blanks), horizontal and vertical 
tabs, newline characters and comments. Whitespace can serve to indicate where 
tokens start and end, but beyond this function, any surplus whitespace is discarded. 
For example, two sequences 

int i; float f; 

and 

int 

i ; 

float f; 
are lexically equivalent and parse identically to give six tokens: 

int 

i 

float 

f 
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Whitespace in Strings 

The ASCII characters representing whitespace can occur within string literals. In that 
case they are protected from the normal parsing process (they remain as a part of 
the string). For example, 

char name[ ] = "mikro foo"; 

parses into seven tokens, including a single string literal token: 

char 

name 



'mikro foo" /* just one token here! */ 



Line Splicing with Backslash (\) 

A special case occurs if a line ends with a backslash (\). Both backslash and new 
line character are discarded, allowing two physical lines of a text to be treated as 
one unit. So, the following code 

"mikroC PRO \ 
for PIC Compiler" 

parses into "mikroC pro for pic compiler". Refer to String Constants for more 
information. 
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COMMENTS 

Comments are pieces of a text used to annotate a program and technically are 
another form of whitespace. Comments are for the programmer's use only; they are 
stripped from the source text before parsing. There are two ways to delineate com- 
ments: the C method and the C++ method. Both are supported by mikroC PRO for 
PIC. 

You should also follow the guidelines on the use of whitespace and delimiters in 
comments, discussed later in this topic to avoid other portability problems. 

C comments 

C comment is any sequence of characters placed after the symbol pair /*. The com- 
ment terminates at the first occurance of the pair */ following the initial /*. The entire 
sequence, including four comment-delimiter symbols, is replaced by one space after 
macro expansion. 

In the mikroC PRO for PIC, 

int /* type * / i /* identifier */; 

parses as: 

int i ; 

Note that the mikroC PRO for PIC does not support a nonportable token pasting 
strategy using /**/. For more information on token pasting, refer to the Preprocessor 
Operators. 

C++ comments 

The mikroC PRO for PIC allows single-line comments using two adjacent slashes 
(//). The comment can start in any position and extends until the next new line. 

The following code 

int i ; // this is a comment 
int j ; 

parses as: 

int i ; 
int j ; 
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Nested comments 

ANSI C doesn't allow nested comments. The attempt to nest a comment like this 

/* int /* declaration */ i; */ 

fails, because the scope of the first /* ends at the first * /. This gives us 

i; */ 

which would generate a syntax error. 
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TOKENS 

Token is the smallest element of a C program that compiler can recognize. The pars- 
er separates tokens from the input stream by creating the longest token possible 
using the input characters in a left-to-right scan. 

The mikroC PRO for PIC recognizes the following kinds of tokens: 

- keywords 

- identifiers 

- constants 

- operators 

- punctuators (also known as separators) 

Token Extraction Example 

Here is an example of token extraction. Take a look at the following example code 
sequence: 

inter = a+++b; 

First, note that inter would be parsed as a single identifier, rather than as the key- 
word int followed by the identifier er. 

The programmer who has written the code might have intended to write inter 
a + (++b) , but it wouldn't work that way. The compiler would parse it into the 
seven following tokens: 

inter // variable identifier 

= // assignment operator 

a // variable identifier 

++ // postincrement operator 

+ // addition operator 

b // variable identifier 

; // statement terminator 

Note that + + + parses as ++ (the longest token possible) followed by +. 
According to the operator precedence rules, our code sequence is actually: 

inter (a++)+b; 
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CONSTANTS 

Constants or literals are tokens representing fixed numeric or character values. 
The mikroC PRO for PIC supports: 

- integer constants 

- floating point constants 

- character constants 

- string constants (strings literals) 

- enumeration constants 

The data type of a constant is deduced by the compiler using such clues as a 
numeric value and format used in the source code. 



Integer Constants 

Integer constants can be decimal (base 10), hexadecimal (base 16), binary (base 
2), or octal (base 8). In the absence of any overriding suffixes, the data type of an 
integer constant is derived from its value. 

Long and Unsigned Suffixes 

The suffix l (or I) attached to any constant forces that constant to be represented 
as a long. Similarly, the suffix u (or u) forces a constant to be unsigned. Both l and 
u suffixes can be used with the same constant in any order or case: ui, lu, ul, 
etc. 

In the absence of any suffix (u, u, l, or l), a constant is assigned the "smallest" of 
the following types that can accommodate its value: short, unsigned short, 

int, unsigned int, long int, unsigned long int. 

Otherwise: 

■ If a constant has the u suffix, its data type will be the first of the following that 

Can accommodate its value: unsigned short, unsigned int, unsigned 
long int. 

■ If a constant has the l suffix, its data type will be the first of the following that can 

accommodate its value: long int, unsigned long int. 

■ If a constant has both l and u suffixes, (lu or ul), its data type will be uns igned 

long int. 
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Decimals 

Decimal constants from -2147483648 to 4294967295 are allowed. Constants 
exceeding these bounds will produce an "Out of range" error. Decimal constants 
must not use an initial zero. An integer constant that has an initial zero is interpret- 
ed as an octal constant. Thus, 

int i = 10; /* decimal 10 */ 
int i = 010; /* decimal 8 */ 
int i = 0; /* decimal = octal */ 

In the absence of any overriding suffixes, the data type of a decimal constant is 
derived from its value, as shown below: 



Value Assigned to Constant 


Assumed Type 


< -2147483648 


Error: Out of range! 


-2147483648 --32769 


long 


-32768- -129 


int 


-128-127 


short 


128-255 


unsigned short 


256 - 32767 


int 


32768 - 65535 


unsigned int 


65536-2147483647 


long 


2147483648 - 4294967295 


unsigned long 


> 4294967295 


Error: Out of range! 



Hexadecimal Constants 

All constants starting with Ox (or Ox) are taken to be hexadecimal. In the absence 
of any overriding suffixes, the data type of an hexadecimal constant is derived from 
its value, according to the rules presented above. For example, 0xC367 will be treat- 
ed as unsigned int. 
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Binary Constants 

All constants starting with Ob (or Ob) are taken to be binary. In the absence of any over- 
riding suffixes, the data type of an binary constant is derived from its value, according 
to the rules presented above. For example, obiiioi will be treated as short. 

Octal Constants 

All constants with an initial zero are taken to be octal. If an octal constant contains 
the illegal digits 8 or 9, an error is reported. In the absence of any overriding suffix- 
es, the data type of an octal constant is derived from its value, according to the rules 
presented above. For example, 0777 will be treated as int. 

Floating Point Constants 

A floating-point constant consists of: 

- Decimal integer 

- Decimal point 

- Decimal fraction 

- e or e and a signed integer exponent (optional) 

- Type suffix: f or f or l or l (optional) 

Either decimal integer or decimal fraction (but not both) can be omitted. Either dec- 
imal point or letter e (or e) with a signed integer exponent (but not both) can be omit- 
ted. These rules allow conventional and scientific (exponent) notations. 

Negative floating constants are taken as positive constants with an unary operator 
minus (-) prefixed. 

The mikroC PRO for PIC limits floating-point constants to the range 
±1.17549435082 * 10-38 .. ±6.80564774407 * 1038. 

Here are some examples: 



0. 


// = 


0.0 


-1.23 


// = 


-1.23 


23.45e6 


// = 


23.45 * 10*6 


2e-5 


// = 


2.0 * 10*-5 


3E+10 


// = 


3.0 * 10*10 


.09E34 


// = 


0.09 * 10*34 



The mikroC PRO for PIC floating-point constants are of the type double. Note that 
the mikroC PRO for PIC's implementation of ANSI Standard considers float and 
double (together with the long double variant) to be the same type. 
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Character Constants 

A character constant is one or more characters enclosed in single quotes, such as 
'A', ' + ', or '\n' . In the mikroC PRO for PIC, single-character constants are 
of the unsigned int type. Multi-character constants are referred to as string con- 
stants or string literals. For more information refer to String Constants. 

Escape Sequences 

A backslash character (\ ) is used to introduce an escape sequence, which allows a 
visual representation of certain nongraphic characters. One of the most common 
escape constants is the newline character (\n). 

A backslash is used with octal or hexadecimal numbers to represent an ASCII symbol 
or control code corresponding to that value; for example, '\x3f t for the question 
mark. Any value within legal range for data type char (0 to OxFF for the mikroC PRO 
for PIC) can be used. Larger numbers will generate the compiler error "Out of range". 
For example, the octal number \ 777 is larger than the maximum value allowed (\ 377) 
and will generate an error. The first nonoctal or nonhexadecimal character encountered 
in an octal or hexadecimal escape sequence marks the end of the sequence. 



Note: You must use the sequence 
operating system paths. 



to represent an ASCII backslash, as used in 



The following table shows the available escape sequences: 



Sequence 



\a 


















Value 















\xH 



\XH 



0x07 



0x08 



OxOC 



OxOA 



OxOD 



0x09 



OxOB 



0x5C 



0x27 



0x22 



0x3F 



Char 



BEL 



BS 



FF 



LF 



CR 



HT 



Audible bell 



Carriage Return 



Tab (horizontal) 



VT 



any 



any 



any 



Description 



Backspace 



Formfeed 



Newline (Linefeed) 



Vertical Tab 



Backslash 



Single quote (Apostrophe) 



Double quote 



Question mark 



O = string of up to 3 octal digits 



H = string of hex digits 



H = string of hex digits 
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Disambiguation 

Some ambiguous situations might arise when using escape sequences. 
Here is an example: 

Lcd_Out_Cp("\x091.0 Intro"); 

This is intended to be interpreted as \x0 9 and "l.o Intro". However, the mikroC 
PRO for PIC compiles it as the hexadecimal number \x09i and literal string ".o 
intro". To avoid such problems, we could rewrite the code in the following way: 

Lcd_Out_Cp ("\x09" "1.0 Intro"); 

For more information on the previous line, refer to String Constants. 

Ambiguities might also arise if an octal escape sequence is followed by a nonoctal 
digit. For example, the following constant: 

"\118" 

would be interpreted as a two-character constant made up of the characters \ 11 and 
8, because 8 is not a legal octal digit. 

String Constants 

String constants, also known as string literals, are a special type of constants which 
store fixed sequences of characters. A string literal is a sequence of any number of 
characters surrounded by double quotes: 

"This is a string." 

The null string, or empty string, is written like "". A literal string is stored internally 
as a given sequence of characters plus a final null character. A null string is stored 
as a single null character. 

The characters inside the double quotes can include escape sequences. This code, 
for example: 

"\ t\ "Name\ "\ \ \ tAddre s s\ n\ n " 

prints like this: 

"Name"\ Address 
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The "Name" is preceded by two tabs; The Address is preceded by one tab. The line 
is followed by two new lines. The " provides interior double quotes. The escape 
character sequence \\ is translated into \ by the compiler. 

Adjacent string literals separated only by whitespace are concatenated during the 
parsing phase. For example: 

"This is " "just" 
" an example . " 

is equivalent to 

"This is just an example." 

Line Continuation with Backslash 

You can also use the backslash (\) as a continuation character to extend a string 
constant across line boundaries: 

"This is really \ 

a one-line string." 

Enumeration Constants 

Enumeration constants are identifiers defined in enum type declarations. The identi- 
fiers are usually chosen as mnemonics to contribute to legibility. Enumeration con- 
stants are of int type. They can be used in any expression where integer constants 
are valid. 

For example: 

enum weekdays { SUN = 0, MON, TUE, WED, THU, FRI, SAT } ; 

The identifiers (enumerators) used must be unique within the scope of the enum dec- 
laration. Negative initializers are allowed. See Enumerations for details about enum 
declarations. 
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Pointer Constants 

A pointer or pointed-at object can be declared with the const modifier. Anything 
declared as const cannot change its value. It is also illegal to create a pointer that 
might violate a non-assignability of the constant object. 

Consider the following examples: 

int i ; // i is an int 

int * pi; // pi is a pointer to int (uninitialized) 

int * const cp = &i; // cp is a constant pointer to int 

const int ci = 7; // ci is a constant int 

const int * pci; // pci is a pointer to constant int 

const int * const cpc = Sci; // cpc is a constant pointer to a 

// constant int 

The following assignments are legal: 

i = ci; // Assign const-int to int 

* cp = ci; // Assign const-int to 

// object-pointed-at-by-a -const -pointer 
++pci; // Increment a pointer-to-const 

pci = cpc; // Assign a const-pointer-to-a-const to a 

// pointer-to-const 

The following assignments are illegal: 

ci = 0; // NO--cannot assign to a const-int 

ci--; // NO--cannot change a const-int 

*pci = 3; // NO--cannot assign to an object 

// pointed at by pointer-to-const . 
cp = &ci; // NO--cannot assign to a const-pointer , 

// even if value would be unchanged. 
cpc++; // NO--cannot change const-pointer 

pi = pci; // NO--if this assignment were allowed, 

// you would be able to assign to *pci 

// (a const value) by assigning to *pi . 

Similar rules are applayed to the volatile modifier. Note that both const and 
volatile can appear as modifiers to the same identifier. 
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Constant Expressions 

A constant expressions can be evaluated during translation rather that runtime and 
accordingly may be used in any place that a constant may be. 

Constant expressions can consist only of the following: 

- literals, 

- enumeration constants, 

- simple constants (no constant arrays or structures), 

- sizeof operators. 

Constant expressions cannot contain any of the following operators, unless the 
operators are contained within the operand of a sizeof operator: assignment, 
comma, decrement, function call, increment. 

Each constant expression can evaluate to a constant that is in the range of repre- 
sentable values for its type. 

Constant expression can be used anywhere a constant is legal. 
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KEYWORDS 

Keywords are words reserved for special purposes and must not be used as normal 
identifier names. 

Beside standard C keywords, all relevant SFR are defined as global variables and 
represent reserved words that cannot be redefined (for example: tmro, pcl, etc). 
Probe the Code Assistant for specific letters (Ctrl+Space in Editor) or refer to Pre- 
defined Globals and Constants. 

Here is an alphabetical listing of keywords in C: 

- asm 

- auto 

- break 

- case 

- char 

- const 

- continue 

- default 

- do 

- double 

- else 

- enum 

- extern 

- float 

- for 

- goto 

- if 

- int 

- long 

- register 

- return 

- short 

- signed 

- sizeof 

- static 

- struct 

- switch 

- typedef 

- union 

- unsigned 

- void 

- volatile 

- while 

Also, the mikroC PRO for PIC includes a number of predefined identifiers used in 
libraries. You could replace them by your own definitions, if you want to develop your 
own libraries. For more information, see mikroC PRO for PIC Libraries. 
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IDENTIFIERS 

Identifiers are arbitrary names of any length given to functions, variables, symbolic 
constants, user-defined data types, and labels. All these program elements will be 
referred to as objects throughout the help (don't get confused with the meaning of 
object in object-oriented programming). 

Identifiers can contain the letters a to z and A to Z, underscore character "_", and 
digits to 9. The only restriction is that the first character must be a letter or an 
underscore. 



Case Sensitivity 

The mikroC PRO for PIC identifiers aren't case sensitive by default, so that sum, sum, 
and sum represent an equivalent identifier. Case sensitivity can be activated or sus- 
pended in Output Settings window. Even if case sensitivity is turned off Keywords 
remain case sensitive and they must be written in lower case. 

Uniqueness and Scope 

Although identifier names are arbitrary (according to the stated rules), if the same 
name is used for more than one identifier within the same scope and sharing the 
same name space then error arises. Duplicate names are legal for different name 
spaces regardless of scope rules. For more information on scope, refer to Scope 
and Visibility. 

Identifier Examples 

Here are some valid identifiers: 

temper at ure_Vl 

Pressure 

no hit 

dat2string 

SUM3 

_vtext 

... and here are some invalid identifiers: 

7temp // NO -- cannot begin with a numeral 

%higher // NO -- cannot contain special characters 

int // NO -- cannot match reserved word 

j23.07.04 // NO -- cannot contain special characters (dot) 
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PUNCTUATORS 

The mikroC PRO for PIC punctuators (also known as separators) are: 

- [ ] - Brackets 

- ( ) - Parentheses 

- { } - Braces 

- , - Comma 

- ; - Semicolon 

- : - Colon 

- * -Asterisk 

- = - Equal sign 

- #- Pound sign 

Most of these punctuators also function as operators. 
Brackets 

Brackets i i indicate single and multidimensional array subscripts: 

char ch, str[ ] = "mikro"; 

int mat[ 3] [ 4] ; /* 3 x 4 matrix */ 
ch = str[ 3] ; /* 4th element */ 

Parentheses 

Parentheses < ) are used to group expressions, isolate conditional expressions, 
and indicate function calls and function parameters: 

d = c * (a + b) ; /* override normal precedence */ 

if (d == z) ++x; /* essential with conditional statement */ 

f unc ( ) ; /* function call, no args */ 

void func2(int n) ; /* function declaration with parameters */ 

Parentheses are recommended in macro definitions to avoid potential precedence 
problems during an expansion: 

#define CUBE (x) ( (x) * (x) * (x) ) 

For more information, refer to Operators Precedence And Associativity and Expres- 
sions. 
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Braces 

Braces { } indicate the start and end of a compound statement: 

if (d == z) { 

++x; 

f unc ( ) ; 
} 

Closing brace serves as a terminator for the compound statement, so a semicolon 
is not required after } , except in structure declarations. Sometimes, the semicolon 
can be illegal, as in 

if (statement) 

{ . . . } ; /* illegal semicolon! */ 
else 

{ . . . } ; 

For more information, refer to the Compound Statements. 

Comma 

Comma (, ) separates the elements of a function argument list: 

void func(int n, float f, char ch); 

Comma is also used as an operator in comma expressions. Mixing two uses of 
comma is legal, but you must use parentheses to distinguish them. Note that (expl , 
exp2) evalutates both but is equal to the second: 

func(i, j ) ; /* call func with two args */ 

func((expl, exp2 ) , (exp3, exp4, exp5)); /* also calls func with two 
args ! * / 

Semicolon 

Semicolon (,• ) is a statement terminator. Any legal C expression (including the empty 
expression) followed by a semicolon is interpreted as a statement, known as an 
expression statement. The expression is evaluated and its value is discarded. If the 
expression statement has no side effects, the mikroC PRO for PIC might ignore it. 

a + b; /* Evaluate a + b, but discard value */ 

++a; /* Side effect on a, but discard value of ++a */ 

; /* Empty expression , or a null statement */ 
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Semicolons are sometimes used to create an empty statement: 

for (i = 0; i < n; i++) ; 

For more information, see the Statements. 

Colon 

Use colon (:) to indicate the labeled statement: 

start: x = 0; 
goto start; 

Labels are discussed in the Labeled Statements. 
Asterisk (Pointer Declaration) 

Asterisk (*) in a variable declaration denotes the creation of a pointer to a type: 

char *char ptr; /* a pointer to char is declared */ 

Pointers with multiple levels of indirection can be declared by indicating a pertinent 
number of asterisks: 

int **int ptr; /* a pointer to an array of integers */ 

double ***double ptr; /* a pointer to a matrix of doubles */ 

You can also use asterisk as an operator to either dereference a pointer or as mul- 
tiplication operator: 

i = * int ptr; 
a = b * 3.14; 

For more information, see the Pointers. 



Equal Sign 
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Equal sign (-) separates variable declarations from initialization lists: 

int test[ 5] = { 1, 2, 3,4,5} ; 
int x = 5; 

Equal sign is also used as an assignment operator in expressions: 

int a, b, c; 
a = b + c; 

For more information, see Assignment Operators. 

Pound Sign (Preprocessor Directive) 

Pound sign (#) indicates a preprocessor directive when it occurs as the first non- 
whitespace character on a line. It signifies a compiler action, not necessarily asso- 
ciated with a code generation. See the Preprocessor Directives for more informa- 
tion. 

# and ## are also used as operators to perform token replacement and merging dur- 
ing the preprocessor scanning phase. See the Preprocessor Operators. 
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CONCEPTS 

This section covers some basic concepts of language, essential for understanding 
of how C programs work. First, we need to establish the following terms that will be 
used throughout the help: 

- Objects and lvalues 

- Scope and Visibility 

- Name Spaces 

- Duration 

Objects 

An object is a specific region of memory that can hold a fixed or variable value (or 
set of values). This use of a term object is different from the same term, used in 
object-oriented languages, which is more general. Our definiton of the word would 
encompass functions, variables, symbolic constants, user-defined data types, and 
labels. 

Each value has an associated name and type (also known as a data type). The 
name is used to access the object and can be a simple identifier or complex expres- 
sion that uniquely refers the object. 

Objects and Declarations 

Declarations establish a necessary mapping between identifiers and objects. Each 
declaration associates an identifier with a data type. 

Associating identifiers with objects requires each identifier to have at least two attrib- 
utes: storage class and type (sometimes referred to as data type). The mikroC PRO 
for PIC compiler deduces these attributes from implicit or explicit declarations in the 
source code. Usually, only the type is explicitly specified and the storage class spec- 
ifier assumes the automatic value auto. 

Generally speaking, an identifier cannot be legally used in a program before its dec- 
laration point in the source code. Legal exceptions to this rule (known as forward ref- 
erences) are labels, calls to undeclared functions, and struct or union tags. 
The range of objects that can be declared includes: 

- Variables 

- Functions 

- Types 

- Arrays of other types 

- Structure, union, and enumeration tags 
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- Structure members 

- Union members 

- Enumeration constants 

- Statement labels 

- Preprocessor macros 

The recursive nature of the declarator syntax allows complex declarators. You'll 
probably want to use typedefs to improve legibility if constructing complex objects. 

Lvalues 

Lvalue is an object locator: an expression that designates an object. An example of 
lvalue expression is * p, where p is any expression evaluating to a non-null pointer. 
A modifiable lvalue is an identifier or expression that relates to an object that can be 
accessed and legally changed in memory. A const pointer to a constant, for exam- 
ple, is not a modifiable lvalue. A pointer to a constant can be changed (but its deref- 
erenced value cannot). 

Historically, I stood for "left", meaning that lvalue could legally stand on the left (the 
receiving end) of an assignment statement. Now only modifiable lvalues can legal- 
ly stand to the left of an assignment operator. For example, if a and b are noncon- 
stant integer identifiers with properly allocated memory storage, they are both mod- 
ifiable lvalues, and assignments such as a = l and b = a + b are legal. 

Rvalues 

The expression a + b is not lvalue: a + b == a is illegal because the expression 
on the left is not related to an object. Such expressions are sometimes called rval- 
ues (short for right values). 
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Scope and Visibility 
Scope 

The scope of an identifier is a part of the program in which the identifier can be used 
to access its object. There are different categories of scope: block (or local), func- 
tion, function prototype, and file. These categories depend on how and where iden- 
tifiers are declared. 

■ Block: The scope of an identifier with block (or local) scope starts at the declara 
tion point and ends at the end of the block containing the declaration (such block 
is known as the enclosing block). Parameter declarations with a function defini 
tion also have block scope, limited to the scope of the function body. 

■ File: File scope identifiers, also known as globals, are declared outside of all 
blocks; their scope is from the point of declaration to the end of the source file. 

■ Function: The only identifiers having function scope are statement labels. Label 
names can be used with goto statements anywhere in the function in which the 
label is declared. Labels are declared implicitly by writing labeiname: fol 
lowed by a statement. Label names must be unique within a function. 

■ Function prototype: Identifiers declared within the list of parameter declarations 
in a function prototype (not as a part of a function definition) have a function pro 
totype scope. This scope ends at the end of the function prototype. 

Visibility 

The visibility of an identifier is a region of the program source code from which an 
identifier's associated object can be legally accessed. 

Scope and visibility usually coincide, though there are circumstances under which 
an object becomes temporarily hidden by the appearance of a duplicate identifier: 
the object still exists but the original identifier cannot be used to access it until the 
scope of the duplicate identifier ends. 

Technically, visibility cannot exceed a scope, but a scope can exceed visibility. See 
the following example: 

void f (int i) { 

int j ; // auto by default 

j = 3 ; // int i and j are in scope and visible 

{ // nested block 

double j ; // j is local name in the nested block 

j = 0.1; // i and double j are visible; 

// int j = 3 in scope but hidden 
} 
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// double j out of scope 
j += 1; // int j visible and = 4 

} 
// i and j are both out of scope 

Name Spaces 

Name space is a scope within which an identifier must be unique. The mikroC PRO 
for PIC uses four distinct categories of identifiers: 

1. goto label names - must be unique within the function in which they are 
declared. 

2. Structure, union, and enumeration tags - must be unique within the block in 
which they are defined. Tags declared outside of any function must be unique. 

3. Structure and union member names - must be unique within the structure or 
union in which they are defined. There is no restriction on the type or offset of 
members with the same member name in different structures. 

4. Variables, typedefs, functions, and enumeration members - must be unique with 
in the scope in which they are defined. Externally declared identifiers must be 
unique among externally declared variables. 

Duplicate names are legal for different name spaces regardless of the scope rules. 

For example: 

int blue = 73; 

{ // open a block 

enum colors { black, red, green, blue, violet, white } c; 

/* enumerator blue = 3 now hides outer declaration of int blue */ 

struct colors { int i, j ; } ; // ILLEGAL: colors duplicate tag 

double red =2; // ILLEGAL: redefinition of red 

} 

blue = 37; // back in int blue scope 



Duration 

Duration, closely related to a storage class, defines a period during which the declared iden- 
tifiers have real, physical objects allocated in memory. We also distinguish between com- 
pile-time and run-time objects. Variables, for instance, unlike typedefs and types, have real 
memory allocated during run time. There are two kinds of duration: static and local. 
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Static Duration 

Memory is allocated to objects with static duration as soon as execution is under- 
way; this storage allocation lasts until the program terminates. Static duration 
objects usually reside in fixed data segments allocated according to the memory 
specifier in force. All globals have static duration. All functions, wherever defined, 
are objects with static duration. Other variables can be given static duration by using 
the explicit static or extern storage class specifiers. 

In the mikroC PRO for PIC, static duration objects are not initialized to zero (or null) 
in the absence of any explicit initializer. 

Don't mix static duration with file or global scope. An object can have static duration 
and local scope - see the example below. 

Local Duration 

Local duration objects are also known as automatic objects. They are created on the 
stack (or in a register) when an enclosing block or a function is entered. They are 
deallocated when the program exits that block or function. Local duration objects 
must be explicitly initialized; otherwise, their contents are unpredictable. 
The storage class specifier auto can be used when declaring local duration variables, but 
it is usually redundant, because auto is default for variables declared within a block. 

An object with local duration also has local scope because it does not exist outside 
of its enclosing block. On the other hand, a local scope object can have static dura- 
tion. For example: 

void f() { 

/* local duration variable; init a upon every call to f * / 
int a = 1 ; 

/* static duration variable; init b only upon first call to f * / 
static int b = 1; 
/* checkpoint! */ 
a++; 
b + +; 
} 

void main ( ) { 

/* At checkpoint, we will have: */ 



f(); 


// 


a=l, 


b=l, 


after first call, 


f 0; 


// 


a=l, 


b=2, 


after second call, 


f 0; 


// 
// 


a=l, 
etc. 


b=3, 


after third call, 
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TYPES 

The mikroC PRO for PIC is a strictly typed language, which means that every object, 
function, and expression must have a strictly defined type, known in the time of com- 
pilation. Note that the mikroC PRO for PIC works exclusively with numeric types. 

The type serves: 

■ to determine the correct memory allocation required initially. 

■ to interpret the bit patterns found in the object during subsequent access. 

■ in many type-checking situations, to ensure that illegal assignments are trapped. 

The mikroC PRO for PIC supports many standard (predefined) and user-defined 
data types, including signed and unsigned integers in various sizes, floating-point 
numbers with various precisions, arrays, structures, and unions. In addition, point- 
ers to most of these objects can be established and manipulated in memory. 

The type determines how much memory is allocated to an object and how the pro- 
gram will interpret the bit patterns found in the object's storage allocation. A given 
data type can be viewed as a set of values (often implementation-dependent) that 
identifiers of that type can assume, together with a set of operations allowed with 
these values. The compile-time operator sizeof allows you to determine the size 
in bytes of any standard or user-defined type. 

The mikroC PRO for PIC standard libraries and your own program and header files must 
provide unambiguous identifiers (or expressions derived from them) and types so that the 
mikroC PRO for PIC can consistently access, interpret, and (possibly) change the bit pat- 
terns in memory corresponding to each active object in your program. 

Type Categories 

A common way to categorize types is to divide them into: 

- fundamental 

- derived 

The fudamental types represent types that cannot be split up into smaller parts. They are 
sometimes referred to as unstructured types. The fundamental types are void, char, 

int, float, and double, together With short, long, signed, and unsigned vari- 
ants of some of them. For more information on fundamental types, refer to the topic Fun- 
damental Types. 

The derived types are also known as structured types and they include pointers to 
other types, arrays of other types, function types, structures, and unions. For more 
information on derived types, refer to the topic Derived Types. 
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Fundamental Types 

The fudamental types represent types that cannot be divided into more basic ele- 
ments, and are the model for representing elementary data on machine level. The 
fudamental types are sometimes referred to as unstructured types, and are used as 
elements in creating more complex derived or user-defined types. 

The fundamental types include: 

- Arithmetic Types 

- Enumerations 

- Void Type 

Arithmetic Types 

The arithmetic type specifiers are built up from the following keywords: void, char, 
int, float and double, together with the prefixes short, long, signed and 
unsigned. From these keywords you can build both integral and floating-point types. 

Integral Types 

The types char and int, together with their variants, are considered to be integral 
data types. Variants are created by using one of the prefix modifiers short, long, 

signed and unsigned. 

In the table below is an overview of the integral types - keywords in parentheses 
can be (and often are) omitted. 

The modifiers signed and unsigned can be applied to both char and int. In the 
absence of the unsigned prefix, signed is automatically assumed for integral types. 
The only exception is char, which is unsigned by default. The keywords signed 

and unsigned, when used On their Own, mean signed int and unsigned int, 

respectively. 

The modifiers short and long can only be applied to int. The keywords short 
and long, used on their own, mean short int and long int, respectively. 
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Type 


Size in Bytes 


Range 


(unsigned) char 


1 


.. 255 


signed char 


1 


- 128 .. 127 


(signed) short (int) 


1 


- 128 .. 127 


unsigned short (int) 


1 


.. 255 


(signed) int 


2 


-32768 .. 32767 


unsigned (int) 


2 


.. 65535 


(signed) long (int) 


4 


-2147483648 .. 2147483647 


unsigned long (int) 


4 


.. 4294967295 



Floating-point Types 

The types float and double, together with the long double variant, are consid- 
ered to be floating-point types. The mikroC PRO for PIC's implementation of an 
ANSI Standard considers all three to be the same type. 

Floating point in the mikroC PRO for PIC is implemented using the Microchip AN575 
32-bit format (IEEE 754 compliant). 

An overview of the floating-point types is shown in the table below: 



Type 


Size in Bytes 


Range 


float 


4 


-1.5* 1045 .. +3.4* 1038 


double 


4 


-1.5* 1045 .. +3.4* 1038 


long double 


4 


-1.5* 1045 .. +3.4* 1038 
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Enumerations 

An enumeration data type is used for representing an abstract, discreet set of val- 
ues with appropriate symbolic names. 

Enumeration Declaration 

Enumeration is declared like this: 

enum tag {enumeration-list} ; 

Here, tag is an optional name of the enumeration; enumeration-list is a comma- 
delimited list of discreet values, enumerators (or enumeration constants). Each enu- 
merator is assigned a fixed integral value. In the absence of explicit initializers, the 
first enumerator is set to zero, and the value of each succeeding enumerator is set 
to a value of its predecessor increased by one. 

Variables of the enum type are declared the same as variables of any other type. For 
example, the following declaration: 

enum colors { black, red, green, blue, violet, white } c; 

establishes a unique integral type, enum colors, variable c of this type, and set of 
enumerators with constant integer values (black = 0, red = 1 , ...). In the mikroC PRO 
for PIC, a variable of an enumerated type can be assigned any value of the type int 
- no type checking beyond that is enforced. That is: 

c = red; // OK 

c = 1 ; // Also OK, means the same 

With explicit integral initializers, you can set one or more enumerators to specific 
values. The initializer can be any expression yielding a positive or negative integer 
value (after possible integer promotions). Any subsequent names without initializers 
will be increased by one. These values are usually unique, but duplicates are legal. 

The order of constants can be explicitly re-arranged. For example: 



colors { 


black, 


// 


value 







red, 


// 


value 


1 




green, 


// 


value 


2 




blue=6, 


// 


value 


6 




violet, 


// 


value 


7 




white=4 } ; 


' // 


value 


4 



1 70 MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



CHAPTER 6 

mikroC PRO for pic Language Reference 

Initializer expression can include previously declared enumerators. For example, in 
the following declaration: 

enum memory sizes { bit = 1, nibble = 4 * bit, byte = 2 * nibble, 

kilobyte = 1024 * byte } ; 

nibble would acquire the value 4, byte the value 8, and kilobyte the value 8192. 

Anomous Enum Type 

In our previous declaration, the identifier colors is an optional enumeration tag that 
can be used in subsequent declarations of enumeration variables of the enum col- 
ors type: 

enum colors bg, border; /* declare variables bg and border */ 

Like with struct and union declarations, you can omit the tag if no further variables 
of this enum type are required: 

/* Anonymous enum type: */ 

enum { black, red, green, blue, violet, white } color; 

Enumeration Scope 

Enumeration tags share the same name space as structure and union tags. Enu- 
merators share the same name space as ordinary variable identifiers: 

int blue = 73; 

{ // open a block 

enum colors { black, red, green, blue, violet, white } c; 

/* enumerator blue = 3 now hides outer declaration of int blue */ 

struct colors { int i, j; } ; // ILLEGAL: colors duplicate tag 
double red =2; // ILLEGAL: redefinition of red 

} 

blue = 37; // back in int blue scope 
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Void Type 

void is a special type indicating the absence of any value. There are no objects of 
void; instead, void is used for deriving more complex types. 

Void Functions 

Use the void keyword as a function return type if the function does not return a 
value. 

void print_temp (char temp) { 
Lcd_Out_Cp ( "Temperature : " ) ; 
Lcd_Out_Cp (temp) ; 

Lcd_Chr_Cp (223) ; // degree character 
Lcd_Chr_Cp( 'C ) ; 

} 

Use void as a function heading if the function does not take any parameters. Alter- 
natively, you can just write empty parentheses: 

main (void) { // same as main ( ) 



Generic Pointers 

Pointers can be declared as void, which means that they can point to any type. 
These pointers are sometimes called generic. 
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Derived Types 

The derived types are also known as structured types. They are used as elements 
in creating more complex user-defined types. 

The derived types include: 

- arrays 

- pointers 

- structures 

- unions 

Arrays 

Array is the simplest and most commonly used structured type. A variable of array 
type is actually an array of objects of the same type. These objects represent ele- 
ments of an array and are identified by their position in array. An array consists of a 
contiguous region of storage exactly large enough to hold all of its elements. 

Array Declaration 

Array declaration is similar to variable declaration, with the brackets added after 
identifer: 

type array name[ constant-expression] 

This declares an array named as array name and composed of elements of type. The 
type can be any scalar type (except void), user-defined type, pointer, enumeration, or 
another array. Result of constant-expression within the brackets determines a number 
of elements in array. If an expression is given in an array declarator, it must evaluate to a 
positive constant integer. The value is a number of elements in an array. 

Each of the elements of an array is indexed from to the number of elements minus 
one. If a number of elements is n, elements of array can be approached as variables 

array name[ 0] . . array name[ n-1] of type. 

Here are a few examples of array declaration: 

#define MAX = 50 

int vector one[ 10] ; /* declares an array of 10 integers */ 

float vector two[ MAX] ; /* declares an array of 50 floats */ 

float vector three[ MAX - 20] ; /* declares an array of 30 floats */ 
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Array Initialization 

An array can be initialized in declaration by assigning it a comma-delimited 
sequence of values within braces. When initializing an array in declaration, you can 
omit the number of elements - it will be automatically determined according to the 
number of elements assigned. For example: 

/* Declare an array which holds number of days in each month: */ 
int days[ 12] = { 31,28,31,30,31,30,31,31,30,31,30,31} ; 

/* This declaration is identical to the previous one */ 
int days[ ] = { 31, 2 8, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31} ; 

If you specify both the length and starting values, the number of starting values must 
not exceed the specified length. The opposite is possible, in this case the trailing 
"excess" elements will be assigned to some encountered runtime values from mem- 
ory. 

In case of array of char, you can use a shorter string literal notation. For example: 

/* The two declarations are identical: */ 
const char msgl[ ] = ('T', 'e', 's', ' t\ '\0'} ; 
const char msg2[ ] = "Test"; 

For more information on string literals, refer to String Constants. 

Arrays n Expressions 

When the name of an array comes up in expression evaluation (except with opera- 
tors & and sizeof), it is implicitly converted to the pointer pointing to array's first 
element. See Arrays and Pointers for more information. 

Multi-dimensional Arrays 

An array is one-dimensional if it is of scalar type. One-dimensional arrays are some- 
times referred to as vectors. 

Multidimensional arrays are constructed by declaring arrays of array type. These 
arrays are stored in memory in such way that the right most subscript changes 
fastest, i.e. arrays are stored "in rows". Here is a sample of 2-dimensional array: 

float m[ 50] [ 20] ; /* 2-dimensional array of size 50x20 */ 

A variable m is an array of 50 elements, which in turn are arrays of 20 floats each. 
Thus, we have a matrix of 50x20 elements: the first element is m[ 0] [ 0] , the last one 
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is m[ 4 9] [ 19] . The first element of the 5th row would be m[ 4] [ 0] . 

If you don't initialize the array in the declaration, you can omit the first dimension of 
multi-dimensional array. In that case, array is located elsewhere, e.g. in another file. 
This is a commonly used technique when passing arrays as function parameters: 

int a[ 3] [ 2] [ 4] ; /* 3-dimensional array of size 3x2x4 */ 

void func (int n[ ] [ 2] [ 4] ) { /* we can omit first dimension * / 

n[ 2] [ 1] [ 3] + + ; /* increment the last element*/ 
} 

void main ( ) { 

func (a) ; 
} 

You can initialize a multi-dimensional array with an appropriate set of values within 
braces. For example: 

int a[ 3][ 2] = {{1,2}, {2,6} , {3,7}} ; 

Pointers 

Pointers are special objects for holding (or "pointing to") memory addresses. In the 
mikroC PRO for PIC, address of an object in memory can be obtained by means of 
an unary operator : . To reach the pointed object, we use an indirection operator ( ) 
on a pointer. 

A pointer of type "pointer to object of type" holds the address of (that is, points to) 
an object of type. Since pointers are objects, you can have a pointer pointing to a 
pointer (and so on). Other objects commonly pointed to include arrays, structures, 
and unions. 

A pointer to a function is best thought of as an address, usually in a code segment, 
where that function's executable code is stored; that is, the address to which control 
is transferred when that function is called. 

Although pointers contain numbers with most of the characteristics of unsigned inte- 
gers, they have their own rules and restrictions for declarations, assignments, con- 
versions, and arithmetic. The examples in the next few sections illustrate these rules 
and restrictions. 
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Pointer Declarations 

Pointers are declared the same as any other variable, but with - ahead of identifier. 
A type at the beginning of declaration specifies the type of a pointed object. A point- 
er must be declared as pointing to some particular type, even if that type is void, 
which really means a pointer to anything. Pointers to void are often called generic 
pointers, and are treated as pointers to char in the mikroC PRO for PIC. 

If type is any predefined or user-defined type, including void, the declaration 

type *p; /* Uninitialized pointer */ 

declares p to be of type "pointer to type". All scoping, duration, and visibility rules 
are applied to the p object just declared. You can view the declaration in this way: if 
*p is an object of type, then p has to be a pointer to such object (object of type). 

Note: You must initialize pointers before using them! Our previously declared point- 
er *p is not initialized (i.e. assigned a value), so it cannot be used yet. 

Note: In case of multiple pointer declarations, each identifier requires an indirect 
operator. For example: 

int *pa, *pb, *pc; 

/* is same as : * / 

int *pa 
int *pb 
int *pc 

Once declared, though, a pointer can usually be reassigned so that it points to an 
object of another type. The mikroC PRO for PIC lets you reassign pointers without 
typecasting, but the compiler will warn you unless the pointer was originally declared 
to be pointing to void. You can assign the void* pointer to the non-void* pointer - 
refer to void for details. 
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Null Pointers 

A null pointer value is an address that is guaranteed to be different from any valid 
pointer in use in a program. Assigning the integer constant to a pointer assigns a 
null pointer value to it. 

For example: 

int * pn =0; /* Here's one null pointer */ 

/* We can test the pointer like this: */ 
if ( pn == ) { . . . } 

The pointer type "pointer to void" must not be confused with the null pointer. The 
declaration 

void * vp ; 

declares that p is a generic pointer capable of being assigned to by any "pointer to 
type" value, including null, without complaint. 

Assignments without proper casting between a "pointer to typei" and a "pointer to 
type2", where typei and type2 are different types, can invoke a compiler warning 
or error. If typei is a function and type2 isn't (or vice versa), pointer assignments 
are illegal. If typei is a pointer to void, no cast is needed. If type2 is a pointer to 
void, no cast is needed. 

Function Pointers 

Function Pointers are pointers, i.e. variables, which point to the address of a func- 
tion. 

// Define a function pointer 

int (*pt2Function) (float, char, char) ; 

Note: Thus functions and function pointers with different calling convention (argu- 
ment order, arguments type or return type is different) are incompatible with each 
other. 
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Assign an address to a Function Pointer 

It's quite easy to assign the address of a function to a function pointer. Simply take 
the name of a suitable and known function. Using the address operator & infront of 
the function's name is optional. 

//Assign an address to the function pointer 

int Dolt (float a, char b, char c){ return a+b+c; } 
pt2Function = SDoIt; // assignment 

Example: 

int addC(char x,char y){ 

return x+y; 
} 

int subC(char x,char y){ 

return x-y; 
} 
int mulC(char x,char y){ 

return x*y; 
} 
int divC(char x,char y){ 

return x/y; 
} 

int mode (char x,char y){ 

return x%y; 
} 

//array of pointer to functions that receive two chars and returns 

int 

int (*arrpf[] ) (char, char) = { addC , subC, mulC, divC, modC} ; 

int res; 

char i ; 

void main ( ) { 

for (i=0;i<5; i++){ 

res = arrpf[ i] (10,20) ; 
} 
} 
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Pointer Arithmetic 

Pointer arithmetic in the mikroC PRO for PIC is limited to: 

- assigning one pointer to another, 

- comparing two pointers, 

- comparing pointer to zero, 

- adding/subtracting pointer and an integer value, 

- subtracting two pointers. 

The internal arithmetic performed on pointers depends on the memory specifier in 
force and the presence of any overriding pointer modifiers. When performing arith- 
metic with pointers, it is assumed that the pointer points to an array of objects. 

Arrays and pointers 

Arrays and pointers are not completely independent types in the mikroC PRO for 
PIC. When the name of an array comes up in expression evaluation (except with 
operators ; and sizeof), it is implicitly converted to the pointer pointing to array's 
first element. Due to this fact, arrays are not modifiable lvalues. 

Brackets [ ] indicate array subscripts. The expression 

id[ exp] 

is defined as 

* ( (id) + (exp)) 

where either: 

- id is a pointer and exp is an integer, or 

- id is an integer and exp is a pointer. 

The following statements are true: 

&a[ i] = a + i 
a[ i] = * (a + i) 

According to these guidelines, it can be written: 

pa = &a[ 4] ; // pa points to a[ 4] 

x = * (pa + 3) ; // x = a[ 7] 

/* .. but: */ 

y = *pa + 3; // y = a[ 4] +3 
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Also the care should be taken when using operator precedence: 

*pa++; // Equal to * (pa++) , increments the pointer 

(*pa)++; // Increments the pointed object! 

The following examples are also valid, but better avoid this syntax as it can make 
the code really illegible: 

(a + 1)[ i] = 3; 

// same as: * ( (a + 1) + i) =3, i.e. a[ i + 1] =3 

(i + 2)[ a] = 0; 

// same as: * ( (i + 2) + a) =0, i.e. a[ i + 2] =0 

Assignment and Comparison 

The simple assignment operator (=) can be used to assign value of one pointer to 
another if they are of the same type. If they are of different types, you must use a 
typecast operator. Explicit type conversion is not necessary if one of the pointers is 
generic (of the void type). 

Assigning the integer constant to a pointer assigns a null pointer value to it. 

Two pointers pointing to the same array may be compared by using relational oper- 
ators ==, !=, <, <=, >, and >=. Results of these operations are the same as if 
they were used on subscript values of array elements in question: 

int *pa = &a[ 4] , *pb = Sa[ 2] ; 

if (pa == pb) { ... /* won't be executed as 4 is not equal to 2 * / } 
if (pa > pb) { . . . /* will be executed as 4 is greater than 2 */ } 

You can also compare pointers to zero value - testing in that way if the pointer actu- 
ally points to anything. All pointers can be successfuly tested for equality or inequal- 
ity to null: 

if (pa == 0) { . . . } 
if (pb != 0) { .. . } 

Note: Comparing pointers pointing to different objects/arrays can be performed at 
programmer's own responsibility — a precise overview of data's physical storage is 
required. 
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Pointer Addition 

You can use operators +, ++, and += to add an integral value to a pointer. The 
result of addition is defined only if the pointer points to an element of an array and 
if the result is a pointer pointing to the same array (or one element beyond it). 

If a pointer is declared to point to type, adding an integral value n to the pointer 
increments the pointer value by n * sizeof (type) as long as the pointer remains 
within the legal range (first element to one beyond the last element). If type has a 
size of 10 bytes, then adding 5 to a pointer to type advances the pointer 50 bytes 
in memory. In case of the type type, the size of a step is one byte. 

For example: 

int a[ 10] ; /* array a containing 10 elements of type int */ 

int *pa = Sa[ 0] ; /* pa is pointer to int, pointing to a[ 0] */ 

* (pa + 3) = 6; /* pa+3 is a pointer pointing to a[ 3] , so a[ 3] 

now equals 6 * / 

pa++; /* pa now points to the next element of array a: 

a[ 1] * / 

There is no such element as "one past the last element", of course, but the pointer 
is allowed to assume such value. C "guarantees" that the result of addition is defined 
even when pointing to one element past array. If P points to the last array element, 
p + l is legal, but p + 2 is undefined. 

This allows you to write loops which access the array elements in a sequence by 
means of incrementing pointer — in the last iteration you will have the pointer point- 
ing to one element past the array, which is legal. However, applying an indirection 
operator (*) to a "pointer to one past the last element" leads to undefined behavior. 

For example: 

void f (some_type a[ ] , int n) { 

/* function f handles elements of array a; */ 

/* array a has n elements of type some_type * / 
int i ; 
some_type *p=Sa[ 0] ; 

for ( i = 0; i < n; i++ ) { 

/* . . here we do something with *p . . */ 
P++; /* . . and with the last iteration p exceeds 
the last element of array a */ 



/* at this point, *p is undefined! */ 



} 
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Pointer Subtraction 

Similar to addition, you can use operators -, , and - = to subtract an integral 

value from a pointer. 

Also, you may subtract two pointers. The difference will be equal to the distance 
between two pointed addresses, in bytes. 

For example: 

int a[ 10] ; 

int *pil = &a[ 0] ; 

int *pi2 = &a[ 4] ; 

i = pi2 - pil; /* i equals 8 */ 

pi2 -= (i » 1) ; /* pi2 = pi2 - 4: pi2 now points to [ 0] */ 
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Structures 

A structure is a derived type usually representing a user-defined collection of named 
members (or components). These members can be of any type, either fundamental 
or derived (with some restrictions to be discussed later), in any sequence. In addi- 
tion, a structure member can be a bit field. 

Unlike arrays, structures are considered to be single objects. The mikroC PRO for 
PIC structure type lets you handle complex data structures almost as easily as sin- 
gle variables. 

Note: the mikroC PRO for PIC does not support anonymous structures (ANSI diver- 
gence). 

Structure Declaration and Initialization 

Structures are declared using the keyword struct:: 

struct tag {member-declarator-list}; 

Here, tag is the name of a structure; member-deciarator-iist is a list of structure 
members, actually a list of variable declarations. Variables of structured type are 
declared the same as variables of any other type. 

The member type cannot be the same as the struct type being currently declared. 
However, a member can be a pointer to the structure being declared, as in the fol- 
lowing example: 

struct mystruct { mystruct s;} ; /* illegal! */ 
struct mystruct {mystruct *ps;} ; /* OK */ 

Also, a structure can contain previously defined structure types when declaring an 
instance of declared structure. Here is an example: 

/* Structure defining a dot: */ 
struct Dot { float x, y;} ; 

/* Structure defining a circle: */ 
struct Circle { 

float r; 

struct Dot center; 
} ol, o2; 
/* declare variables ol and o2 of Circle */ 
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Note that the structure tag can be omitted, but then additional objects of this type cannot be 
declared elsewhere. For more information, see the Untagged Structures below. 

Structure is initialized by assigning it a comma-delimited sequence of values within 
braces, similar to array. For example: 

/* Referring to declarations from the example above: */ 

/* Declare and initialize dots p and q: */ 
struct Dot p = { 1., 1.} , q = { 3.7, -0.5} ; 

/* Declare and initialize circle ol: */ 

struct Circle ol = {1., {0., 0.}} ; // radius is 1, center is at (0, 0) 

Incomplete Declarations 

Incomplete declarations are also known as forward declarations. A pointer to a 
structure type a can legally appear in the declaration of another structure b before 
a has been declared: 

struct A; // incomplete 
struct B { struct A *pa;} ; 
struct A { struct B *pb;} ; 

The first appearance of a is called incomplete because there is no definition for it at 
that point. An incomplete declaration is allowed here, because the definition of b 
doesn't need the size of a. 

Untagged Structures and Typedefs 

If the structure tag is omitted, an untagged structure is created. The untagged 
structures can be used to declare the identifiers in the comma-delimited member- 
deciarator-iist to be of the given structure type (or derived from it), but addition- 
al objects of this type cannot be declared elsewhere. 
It is possible to create a typedef while declaring a structure, with or without tag: 

/* With tag: */ 

typedef struct mystruct { . . . } Mystruct; 

Mystruct s, *ps, arrs[ 10] ; /* same as struct mystruct s, etc. */ 

/* Without tag: */ 

typedef struct { ... } Mystruct; 

Mystruct s, *ps, arrs[ 10] ; 

Usually, there is no need to use both tag and typedef: either can be used in struc- 
ture type declarations. 
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Untagged structure and union members are ignored during initialization. 

Note: See also Working with structures. 

WORKING WITH STRUCTURES 

Structures represent user-defined types. A set of rules regarding the application of 
structures is strictly defined. 

Assignment 

Variables of the same structured type may be assigned one to another by means of 
simple assignment operator (=). This will copy the entire contents of the variable to 
destination, regardless of the inner complexity of a given structure. 
Note that two variables are of the same structured type only if they are both defined 
by the same instruction or using the same type identifier. For example: 

/* a and b are of the same type: */ 
struct { int ml, m2;} a, b; 

/* But c and d are not of the same type although 

their structure descriptions are identical : */ 
struct {int ml, m2;} c; 
struct {int ml, m2;} d; 

Size of Structure 

The size of the structure in memory can be retrieved by means of the operator 
sizeof . It is not necessary that the size of the structure is equal to the sum of its 
members' sizes. It is often greater due to certain limitations of memory storage. 

Structures and Functions 

A function can return a structure type or a pointer to a structure type: 

mystruct funcl (void) ; /* fund () returns a structure */ 
mystruct * f unc2 (void) ; /* func2() returns pointer to structure */ 

A structure can be passed as an argument to a function in the following ways: 

void funcl (mystruct s ; ) ; /* directly */ 
void func2 (mystruct *sptr;); /* via a pointer */ 
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Structure Member Access 

Structure and union members are accessed using the following two selection oper- 
ators: 

- . (period) 

- -> (right arrow) 

The operator . is called the direct member selector and it is used to directly access 
one of the structure's members. Suppose that the object s is of the struct type s and 
m is a member identifier of the type i: declared in s, then the expression 

s.m // direct access to member m 

is of the type m, and represents the member object m in s. 

The operator - is called the indirect (or pointer) member selector. Suppose that the 
object s is of the struct type s and ps is a pointer to s. Then if m is a member iden- 
tifier of the type m declared in s, the expression 

ps->m // indirect access to member m; 
// identical to (*ps) .m 

is of the type k, and represents the member object m in s. The expression ps->m is 
a convenient shorthand for (*ps) .m 

For example: 

struct mystruct { 
int i ; 

char str[ 21] ; 
double d; 

} s, *sptr = ss; 



s.i = 3; // assign to the i member of mystruct s 

sptr -> d = 1.23; // assign to the d member of mystruct s 

The expression s.m is lvalue, providing that s is lvalue and m is not an array type. 
The expression sptr->m is an lvalue unless m is an array type. 
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Accessing Nested Structures 

If the structure b contains a field whose type is the structure a, the members of a can 
be accessed by two applications of the member selectors: 

struct A { 

int j ; double x ; 

} ; 

struct B { 

int i; struct A aa; double d; 

} s, *sptr; 



s.i = 3; // assign 3 to the i member of B 

s.aa.j = 2; // assign 2 to the j member of A 

sptr->d = 1.23; // assign 1.23 to the d member of B 

sptr->aa.x = 3.14; // assign 3.14 to x member of A 

Structure Uniqueness 

Each structure declaration introduces a unique structure type, so that in 

struct A { 

int i , j ; double d ; 

} aa, aaa; 

struct B { 

int i , j ; double d ; 

} bb; 

the objects aa and aaa are both of the type struct a, but the objects aa and bb are 
of different structure types. Structures can be assigned only if the source and desti- 
nation have the same type: 

aa = aaa; /* OK: same type, member by member assignment */ 
aa = bb; /* ILLEGAL: different types */ 

/* but you can assign member by member: */ 
aa . i = bb . i ; 
aa . j = bb . j ; 
aa.d = bb.d; 
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Unions 

Union types are derived types sharing many of syntactic and functional features of 
structure types. The key difference is that a union members share the same mem- 
ory space. 

Note: The mikroC PRO for PIC does not support anonymous unions (ANSI diver- 
gence). 

Unions Declaration 

Unions have the same declaration as structures, with the keyword union used 
instead of struct 

union tag { member-declarator-list } ; 

Unlike structures' members, the value of only one of union's members can be stored 
at any time. Here is a simple example: 

union myunion { // union tag is 'myunion' 
int i ; 
double d ; 
char ch; 

} mu , * pm ; 

The identifier mu, of the type myunion, can be used to hold a2-byte int, 4-byte dou- 
ble or single-byte char, but only one of them at a certain moment. The identifier pm 

is a pointer to union myunion. 

Size of Union 

The size of a union is the size of its largest member. In our previous example, both 
sizeof (union myunion) and sizeof (mu) return 4, but 2 bytes are unused 
(padded) when mu holds the int object, and 3 bytes are unused when mu holds 

char. 

Union Member Access 

Union members can be accessed with the structure member selectors (. and ->), be 
careful when doing this: 

/* Referring to declarations from the example above: */ 

pm = Smu; 

mu . d = 4.016; 

tmp = mu.d; // OK: mu.d = 4.016 
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tmp = mu.i; // peculiar result 

pm-> i = 3 ; 

tmp = mu . i ; / / OK: mu . i = 3 

The third line is legal, since mu . i is an integral type. However, the bit pattern in mu . i 
corresponds to parts of the previously assigned double. As such, it probably won't 
provide an useful integer interpretation. 

When properly converted, a pointer to a union points to each of its members, and 
vice versa. 

Bit Fields 

Bit fields are specified numbers of bits that may or may not have an associated iden- 
tifier. Bit fields offer a way of subdividing structures into named parts of user-defined 
sizes. 

Structures and unions can contain bit fields that can be up to 16 bits. 

You cannot take the address of a bit field. 

Note: If you need to handle specific bits of 8-bit variables (char and unsigned 
short) or registers, you don't need to declare bit fields. Much more elegant solution 
is to use the mikroC PRO for PIC's intrinsic ability for individual bit access — see 
Accessing Individual Bits for more information. 

Bit Fields Declaration 

Bitfields can be declared only in structures and unions. Declare a structure normal- 
ly and assign individual fields like this (fields need to be unsigned): 

struct tag { 

unsigned bitfield- declarator-list; 



Here, tag is an optional name of the structure; bitf ieid-deciarator-iist is a 
list of bit fields. Each component identifer requires a colon and its width in bits to be 
explicitly specified. Total width of all components cannot exceed two bytes (16 bits). 

As an object, bit fields structure takes two bytes. Individual fields are packed within 
two bytes from right to left. In bitfieid-deciarator-iist, you can omit identifi- 
ers) to create an artificial "padding", thus skipping irrelevant bits. 
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For example, if there is a need to manipulate only bits 2-4 of a register as one block, 
create a structure like this: 

struct { 

unsigned : 2, // Skip bits and 1, no identifier here 
mybits : 3; // Relevant bits 2, 3 and 4 

// Bits 5, 6 and 7 are implicitly left out 



} myreg; 

Here is an example: 



typedef struct 

lo nibble 
hi nibble 
high_byte 



myunsigned; 



which declares the structured type myunsigned containing three components: 

lonibble (bits 3..0), hinibble (bits 7. .4) and highbyte (bits 15. .8). 

Bit Fields Access 

Bit fields can be accessed in the same way as the structure members. Use direct 
and indirect member selector (. and ->). For example, we could work with our pre- 
viously declared myunsigned like this: 

// This example writes low byte of bit field of myunsigned type to 

PORTO: 

myunsigned Value For PORTO; 

void main ( ) { 

Value_For_PORT0 .lo_nibble = 7; 
Value_For_PORTO .hi_nibble = OxOC; 
PO = * (char *) (void * ) &Value_For_PORTO; 
// typecasting : 

// 1. address of structure to pointer to void 

// 2. pointer to void to pointer to char 

// 3. dereferencing to obtain the value 



190 
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Type Conversions 

The mikroC PRO for PIC is a strictly typed language, with each operator, statement 
and function demanding appropriately typed operands/arguments. However, we 
often have to use objects of "mismatching" types in expressions. In that case, type 
conversion is needed. 

Conversion of object of one type means that object's type is changed into another 
type. The mikroC PRO for PIC defines a set of standard conversions for built-in 
types, provided by compiler when necessary. For more information, refer to the 
Standard Conversions. 

Conversion is required in the following situations: 

- if a statement requires an expression of particular type (according to language def- 
inition), and we use an expression of different type, 

- if an operator requires an operand of particular type, and we use an operand of dif- 
ferent type, 

- if a function requires a formal parameter of particular type, and we pass it an object 
of different type, 

- if an expression following the keyword return does not match the declared func- 
tion return type, 

- if intializing an object (in declaration) with an object of different type. 

In these situations, compiler will provide an automatic implicit conversion of types, without 
any programmer's interference. Also, the programmer can demand conversion explicitly by 
means of the typecast operator. For more information, refer to the Explicit Typecasting. 

Standard Conversions 

When using arithmetic expression, such as a + b, where a and b are of different 
arithmetic types, the mikroC PRO for PIC performs implicit type conversions before 
the expression is evaluated. These standard conversions include promotions of 
"lower" types to "higher" types in the interests of accuracy and consistency. 

Assigning a signed character object (such as a variable) to an integral object results 
in automatic sign extension. Objects of type signed char always use sign extension; 
objects of type unsigned char always has its high byte set to zero when converted 
to int. 

Converting a longer integral type to a shorter type truncates the higher order bits 
and leaves low-order bits unchanged. Converting a shorter integral type to a longer 
type either sign-extends or zero-fills the extra bits of the new value, depending on 
whether the shorter type is signed or unsigned, respectively. 
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Note: Conversion of floating point data into integral value (in assignments or via 
explicit typecast) produces correct results only if the float value does not exceed 
the scope of destination integral type. 

Details: 

Here are the steps the mikroC PRO for PIC uses to convert the operands in an arith- 
metic expression: 
First, any small integral types are converted according to the following rules: 

1. char converts to int 

2. signed char converts to int, with the same value 

3. short converts to int, with the same value, sign-extended 

4. unsigned short converts to int, with the same value, zero-filled 

5. enum converts to int, with the same value 

After this, any two values associated with an operator are either int (including the 

long and unsigned modifiers) Or float (equivalent With double and long double 

in the mikroC PRO for PIC). 

1 . If either operand is float, the other operand is converted to float. 

2. Otherwise, if either operand is unsigned long, the other operand is converted to 

unsigned long. 

3. Otherwise, if either operand is long, then the other operand is converted to long. 

4. Otherwise, if either operand is unsigned, then the other operand is converted to 

unsigned. 

5. Otherwise, both operands are int. 

The result of the expression is the same type as that of the two operands. 
Here are several examples of implicit conversion: 

2+3.1 /*?2. +3.1? 5.1*/ 

5/4*3. /* ? (5/4)*3. ? 1*3. ? l.*3. ? 3. */ 

3. * 5 / 4 /* ? (3.*5)/4 ? (3.*5.)/4 ? 15. /4 ? 15. /4. ? 3.75 */ 

Pointer Conversion 

Pointer types can be converted to other pointer types using the typecasting mecha- 
nism: 

char *str; 

int * ip; 

str = (char * ) ip; 

More generally, the cast type* will convert a pointer to type "pointer to type". 
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Explicit Type Concersions (Typecasting) 

In most situations, compiler will provide an automatic implicit conversion of types 
where needed, without any user's interference. Also, the user can explicitly convert 
an operand to another type using the prefix unary typecast operator: 

(type) object 

This will convert object to a specified type. Parentheses are mandatory. 
For example: 

/* Let's have two variables of char type: */ 
char a , b ; 

/* Following line will coerce a to unsigned int: */ 
(unsigned int) a; 

/* Following line will coerce a to double, 

then coerce b to double automatically, 

resulting in double type value: */ 
(double) a + b; // equivalent to ( (double) a) + b; 

Declarations 

A declaration introduces one or several names to a program - it informs the compil- 
er what the name represents, what its type is, what operations are allowed with it, 
etc. This section reviews concepts related to declarations: declarations, definitions, 
declaration specifiers, and initialization. 

The range of objects that can be declared includes: 

- Variables 

- Constants 

- Functions 

- Types 

- Structure, union and enumeration tags 

- Structure members 

- Union members 

- Arrays of other types 

- Statement labels 

- Preprocessor macros 
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Declarations and Definitions 

Defining declarations, also known as definitions, beside introducing the name of an 
object, also establish the creation (where and when) of an object; that is, the alloca- 
tion of physical memory and its possible initialization. Referencing declarations, or 
just declarations, simply make their identifiers and types known to the compiler. 

Here is an overview. Declaration is also a definition, except if: 

- it declares a function without specifying its body 

- it has the extern specifier, and has no initializator or body (in case of func.) 

- it is the typedef declaration 

There can be many referencing declarations for the same identifier, especially in a 
multifile program, but only one defining declaration for that identifier is allowed. 

For example: 

/* Here is a nonde fining declaration of function max; */ 
/* it merely informs compiler that max is a function */ 
int max ( ) ; 

/* Here is a definition of function max: */ 
int max (int x, int y) { 

return (x >= y) ? x : y; 
} 

/* Definition of variable i: */ 
int i ; 

/* Following line is an error, i is already defined ! */ 
int i ; 

Declarations and Declarators 

The declaration contains specifier(s) followed by one or more identifiers (declara- 
tors). The declaration begins with optional storage class specifiers, type specifiers, 
and other modifiers. The identifiers are separated by commas and the list is termi- 
nated by a semicolon. 

Declarations of variable identifiers have the following pattern: 

storage-class [ type-qualifier] type varl [ =initl] , var2 [ =init2] , ... ; 

where varl, var2,... are any sequence of distinct identifiers with optional initializers. 
Each of the variables is declared to be of type; if omitted, type defaults to int. The 

Specifier storage-class Can take the values extern, static, register, Or the 
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default auto. Optional type-qualifier can take values const or volatile. For 
more details, refer to Storage Classes and Type Qualifiers. 



For example: 

/* Create 3 integer variables called x, y, and z 

and initialize x and y to the values 1 and 2, respectively: */ 
int x = 1, y = 2, z ; // z remains uninitialized 

/* Create a floating-point variable q with static modifier, 

and initialize it to 0.25: */ 
static float q = .25; 

These are all defining declarations; storage is allocated and any optional initializers 
are applied. 

Linkage 

An executable program is usually created by compiling several independent trans- 
lation units, then linking the resulting object files with preexisting libraries. A term 
translation unit refers to a source code file together with any included files, but with- 
out the source lines omitted by conditional preprocessor directives. A problem aris- 
es when the same identifier is declared in different scopes (for example, in different 
files), or declared more than once in the same scope. 

The linkage is a process that allows each instance of an identifier to be associated 
correctly with one particular object or function. All identifiers have one of two linkage 
attributes, closely related to their scope: external linkage or internal linkage. These 
attributes are determined by the placement and format of your declarations, togeth- 
er with an explicit (or implicit by default) use of the storage class specifier static or 

extern. 

Each instance of a particular identifier with external linkage represents the same 
object or function throughout the entire set of files and libraries making up the pro- 
gram. Each instance of a particular identifier with internal linkage represents the 
same object or function within one file only. 

Linkage Rules 

Local names have internal linkage; the same identifier can be used in different files 
to signify different objects. Global names have external linkage; identifier signifies 
the same object throughout all program files. 

If the same identifier appears with both internal and external linkage within the same 
file, the identifier will have internal linkage. 
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Internal Linkage Rules 

1. names having file scope, explicitly declared as static, have internal linkage 

2. names having file scope, explicitly declared as const and not explicitly declared 
as extern, have internal linkage 

3. typedef names have internal linkage 

4. enumeration constants have internal linkage 

External Linkage Rules 

1 . names having file scope, that do not comply to any of previously stated internal 
linkage rules, have external linkage 

The storage class specifiers auto and register cannot appear in an external dec- 
laration. No more than one external definition can be given for each identifier in a 
translation unit declared with internal linkage. An external definition is an external 
declaration that defines an object or a function and also allocates a storage. If an 
identifier declared with external linkage is used in an expression (other than as part 
of the operand of sizeof), then exactly one external definition of that identifier must 
be somewhere in the entire program. 

Storage Classes 

Associating identifiers with objects requires each identifier to have at least two attrib- 
utes: storage class and type (sometimes referred to as data type). The mikroC PRO 
for PIC compiler deduces these attributes from implicit or explicit declarations in the 
source code. 

A storage class dictates the location (data segment, register, heap, or stack) of 
object and its duration or lifetime (the entire running time of the program, or during 
execution of some blocks of code). A storage class can be established by the syn- 
tax of a declaration, by its placement in the source code, or by both of these factors: 

storage-class type identifier 

The storage class specifiers in the mikroC PRO for PIC are: 

■ auto 

■ register 

■ static 

■ extern 
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Auto 

The auto modifer is used to define that a local variable has a local duration. This is 
the default for local variables and is rarely used, auto can not be used with globals. 
See also Functions. 

Register 

At the moment the modifier register technically has no special meaning. The 
mikroC PRO for PIC compiler simply ignores requests for register allocation. 

Static 

A global name declared with the static specifier has internal linkage, meaning that 
it is local for a given file. See Linkage for more information. 

A local name declared with the static specifier has static duration. Use static with 
a local variable to preserve the last value between successive calls to that function. 
See Duration for more information. 

Extern 

A name declared with the extern specifier has external linkage, unless it has been 
previously declared as having internal linkage. A declaration is not a definition if it 
has the extern specifier and is not initialized. The keyword extern is optional for 
a function prototype. 

Use the extern modifier to indicate that the actual storage and initial value of the 
variable, or body of the function, is defined in a separate source code module. Func- 
tions declared with extern are visible throughout all source files in the program, 
unless the function is redefined as static. 

See Linkage for more information. 

Type Qualifiers 

The type qualifiers const and volatile are optional in declarations and do not 
actually affect the type of declared object. 

Qualifiers Const 

The qualifier const implies that a declared object will not change its value during 
runtime. In declarations with the const qualifier all objects need to be initialized. 

The mikroC PRO for PIC treats objects declared with the const qualifier the same 
as literals or preprocessor constants. If the user tries to change an object declared 
with the const qualifier compiler will report an error. 
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For example: 

const double PI = 3.14159; 

Qualifier Volatile 

The qualifier volatile implies that a variable may change its value during runtime 
independently from the program. Use the volatile modifier to indicate that a variable 
can be changed by a background routine, an interrupt routine, or I/O port. Declaring 
an object to be volatile warns the compiler not to make assumptions concerning the 
value of an object while evaluating expressions in which it occurs because the value 
could be changed at any moment. 

Typedef Specifier 

The specifier typedef introduces a synonym for a specified type. The typedef dec- 
larations are used to construct shorter or more convenient names for types already 
defined by the language or declared by the user. 
The specifier typedef stands first in the declaration: 

typedef <type definition> synonym; 

The typedef keyword assigns Synonym to <type_definition>. The synonym 

needs to be a valid identifier. 

A declaration starting with the typedef specifier does not introduce an object or a 
function of a given type, but rather a new name for a given type. In other words, the 
typedef declaration is identical to a "normal" declaration, but instead of objects, it 
declares types. It is a common practice to name custom type identifiers with start- 
ing capital letter — this is not required by the mikroC PRO for PIC. For example: 

/* Let's declare a synonym for "unsigned long int" */ 
typedef unsigned long int Distance; 

/* Now, synonym "Distance" can be used as type identifier : */ 
Distance i; // declare variable i of unsigned long int 

In the typedef declaration, as in any other declaration, several types can be 
declared at once. For example: 

typedef int *Pti, Array! 10] ; 

Here, pti is a synonym for type "pointer to int", and Array is a synonym for type 
"array of 10 int elements". 
asm Declarations 
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The mikroC PRO for PIC allows embedding assembly in the source code by means 
of the asm declaration. The declarations asm and asm are also allowed in the 
mikroC PRO for PIC and have the same meaning. Note that numerals cannnot be 
used as absolute addresses for SFR or GPR variables in assembly instructions. 
Symbolic names may be used instead (listing will display these names as well as 
addresses). 

Assembly instructions can be grouped by the asm keyword (or , or asm): 

asm { 

block of assembly instructions 



There are two ways to embeding single assembly instruction to C code: 

asm assembly instruction; 

and 

asm assembly instruction 

Note: semicolon and LF are terminating asm scope for single assembly instructions. 
This is the reason why the following syntax is not asm block: 

asm 

{ 

block of assembly instructions 

} 

This code will be interpreted as single empty asm line followed by C compound 
statement. 

The mikroC PRO for PIC comments (both single-line and multi-line) are allowed in 
embedded assembly code. 

if you have a global variable "g_var", that is of type long (i.e. 4 bytes), you are to 
access it like this: 

MOVF g var+0, ;puts least-significant byte of g var in W register 

MOVF g var+1, ; second byte of g var; corresponds to Hi (g var) 

MOVF _g_var+2, ; Higher (g_var) 

MOVF _g_var+3, ; Highest (g_var) 

. . . etc . 

If you want to know details about asm syntax supported by mikroC PRO for PIC it 
is recomended to study asm and 1st files generated by compiler. It is also recomend- 
ed to check "Include source lines in output files" checkbox in Output settings 
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Note: Compiler doesn't expect memory banks to be changed inside the assembly 
code. If the user wants to do this, then he must restore the previous bank selection. 

Related topics: mikroC PRO for PIC specifcs 

Initialization 

The initial value of a declared object can be set at the time of declaration (initializa- 
tion). A part of the declaration which specifies the initialization is called initializer. 

Initializers for globals and static objects must be constants or constant expres- 
sions. The initializer for an automatic object can be any legal expression that eval- 
uates to an assignment-compatible value for the type of the variable involved. 

Scalar types are initialized with a single expression, which can optionally be enclosed 
in braces. The initial value of an object is that of the expression; the same constraints 
for type and conversions as for simple assignments are applied to initializations too. 

For example: 

int i = 1 ; 

char *s = "hello"; 

struct complex c = {0.1, -0.2} ; 

// where 'complex' is a structure (float, float) 

For structures or unions with automatic storage duration, the initializer must be one 
of the following: 

-An initializer list. 

-A single expression with compatible union or structure type. In this case, the initial 

value of the object is that of the expression. 

For example: 

struct dot { int x; int y; } m = { 30, 40} ; 

For more information, refer to Structures and Unions. 

Also, you can initialize arrays of character type with a literal string, optionally 
enclosed in braces. Each character in the string, including the null terminator, initial- 
izes successive elements in the array. For more information, refer to Arrays. 
Automatic Initialization 

The mikroC PRO for PIC does not provide automatic initialization for objects. Unini- 
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tialized globals and objects with static duration will take random values from mem- 
ory. 

FUNCTIONS 

Functions are central to C programming. Functions are usually defined as subpro- 
grams which return a value based on a number of input parameters. Return value 
of the function can be used in expressions - technically, function call is considered 
to be an expression like any other. 

C allows a function to create results other than its return value, referred to as side 
effects. Often, the function return value is not used at all, depending on the side 
effects. These functions are equivalent to procedures of other programming lan- 
guages, such as Pascal. C does not distinguish between procedure and function - 
functions play both roles. 

Each program must have a single external function named main marking the entry 
point of the program. Functions are usually declared as prototypes in standard or 
user-supplied header files, or within program files. Functions have external linkage 
by default and are normally accessible from any file in the program. This can be 
restricted by using the static storage class specifier in function declaration (see 
Storage Classes and Linkage). 

Note: Check the PIC Specifics for more information on functions' limitations on the 
PIC compliant MCUs. 

Function Declaration 

Functions are declared in user's source files or made available by linking precom- 
piled libraries. The declaration syntax of the function is: 

type function name (parameter-declarator-list) ; 

The function name must be a valid identifier. This name is used to call the func- 
tion; see Function Calls for more information. 

type represents the type of function result, and can be of any standard or user- 
defined type. For functions that do not return value the void type should be used. 
The type can be omitted in global function declarations, and function will assume the 
int type by default. 

Function type can also be a pointer. For example, float* means that a function 
result is a pointer to float. The generic pointer void* is also allowed. 
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The function cannot return an array or another function. 

Within parentheses, parameter-deciarator-iist is a list of formal arguments 
that function takes. These declarators specify the type of each function parameter. 
The compiler uses this information to check validity of function calls. If the list is 
empty, a function does not take any arguments. Also, if the list is void, a function 
also does not take any arguments; note that this is the only case when void can 
be used as an argument's type. 

Unlike variable declaration, each argument in the list needs its own type specifier 
and possible qualifier const or volatile. 

Function Prototype 

A function can be defined only once in the program, but can be declared several 
times, assuming that the declarations are compatible. When declaring a function, 
the formal argument's identifier does not have to be specified, but its type does. 

This kind of declaration, commonly known as the function prototype, allows better 
control over argument number, type checking and type conversions. The name of a 
parameter in function prototype has its scope limited to the prototype. This allows 
one parameter identifier to have different name in different declarations of the same 
function: 

/* Here are two prototypes of the same function : */ 

int test (const char*) /* declares function test */ 

int test (const char*p) /* declares the same function test */ 

Function prototypes are very useful in documenting code. For example, the function 
cf init takes two parameters: Control Port and Data Port. The question is, which 
is which? The function prototype: 

void Cf_Init(char *ctrlport, char *dataport); 

makes it clear. If a header file contains function prototypes, the user can read that 
file to get the information needed for writing programs that call these functions. If a 
prototype parameter includes an identifier, then the indentifier is only used for error 
checking. 
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Function Definition 

Function definition consists of its declaration and function body. The function body 
is technically a block - a sequence of local definitions and statements enclosed 
within braces i ; . All variables declared within function body are local to the function, 
i.e. they have function scope. 

The function itself can be defined only within the file scope, which means that func- 
tion declarations cannot be nested. 

To return the function result, use the return statement. The statement return in 
functions of the void type cannot have a parameter - in fact, the return statement 
can be omitted altogether if it is the last statement in the function body. 

Here is a sample function definition: 

/* function max returns greater one of its 2 arguments: */ 

int max (int x, int y) { 
return (x>=y) ? x : y; 

} 

Here is a sample function which depends on side effects rather than return value: 

/* function converts Descartes coordinates (x, y) to polar (r,fi) : */ 
tinclude <math.h> 

void polar (double x, double y, double *r, double *fi) { 

*r = sqrt(x * x + y * y); 

*fi = (x == SS y == 0) ? : atan2 (y, x) ; 

return; /* this line can be omitted */ 
} 

Function Reentrancy 

Functions reentrancy is allowed if the function has no parameters and local vari- 
ables, or if the local variables are placed in the Rx space. Remember that the PIC 
has stack and memory limitations which can varies greatly between MCUs. 
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Function Calls and Argument Conversion 
Function Calls 

A function is called with actual arguments placed in the same sequence as their 
matching formal parameters. Use the function-call operator (): 

function name (expression 1, ... , expression n) 

Each expression in the function call is an actual argument. Number and types of 
actual arguments should match those of formal function parameters. If types do not 
match, implicit type conversions rules will be applied. Actual arguments can be of 
any complexity, but order of their evaluation is not specified. 

Upon function call, all formal parameters are created as local objects initialized by 
the values of actual arguments. Upon return from a function, a temporary object is 
created in the place of the call, and it is initialized by the expression of the return 
statement. This means that the function call as an operand in complex expression 
is treated as a function result. 

If the function has no result (type : id) or the result is not needed, then the func- 
tion call can be written as a self-contained expression. 

In C, scalar arguments are always passed to the function by value. The function can 
modify the values of its formal parameters, but this has no effect on the actual argu- 
ments in the calling routine. A scalar object can be passed by the address if a for- 
mal parameter is declared as a pointer. The pointed object can be accessed by 
using the indirection operator* . 

// For example , Soft Uart Read takes the pointer to error variable , 
// so it can change the value of an actual argument : 
Sof t_Uart_Read (Serror) ; 

// The following code would be wrong; you would pass the value 
// of error variable to the function : 
Sof t_Uart_Read (error) ; 

Argument Conversions 

If a function prototype has not been previously declared, the mikroC PRO for PIC 
converts integral arguments to a function call according to the integral widening 
(expansion) rules described in Standard Conversions. If a function prototype is in 
scope, the mikroC PRO for PIC converts the passed argument to the type of the 
declared parameter according to the same conversion rules as in assignment state- 
ments. 
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If a prototype is present, the number of arguments must match. The types need to 
be compatible only to the extent that an assignment can legally convert them. The 
user can always use an explicit cast to convert an argument to a type that is accept- 
able to a function prototype. 

Note: If the function prototype does not match the actual function definition, the mikroC 
PRO for PIC will detect this if and only if that definition is in the same compilation unit 
as the prototype. If you create a library of routines with the corresponding header file of 
prototypes, consider including that header file when you compile the library, so that any 
discrepancies between the prototypes and actual definitions will be detected. 

The compiler is also able to force arguments to change their type to a proper one. 
Consider the following code: 

int limit = 32; 
char ch = ' A ' ; 
long re s ; 

// prototype 

extern long func(long pari, long par2); 

main ( ) { 

res = tunc (limit, ch) ; // function call 



Since the program has the function prototype for tunc, it converts limit and ch to 
long, using the standard rules of assignment, before it places them on the stack for 
the call to tunc. 

Without the function prototype, limit and ch would be placed on the stack as an 
integer and a character, respectively; in that case, the stack passed to tunc will not 
match size or content that func expects, which can cause problems. 

Ellipsis ('...') Operator 

The ellipsis ('...') consists of three successive periods with no whitespace intervening. 
An ellipsis can be used in the formal argument lists of function prototypes to indicate a 
variable number of arguments, or arguments with varying types. For example: 

void func (int n, char ch, . . . ) ; 

This declaration indicates that func will be defined in such a way that calls must have 
at least two arguments, int and char, but can also have any number of addition- 
al arguments. 
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Example: 

#include <stdarg.h> 

int addvararg (char al,...){ 
va_list ap; 
char temp; 
va_start (ap, al ) ; 

while ( temp = vaarg (ap, char) ) 

al += temp; 
return al; 

} 

int res; 
void main ( ) { 

res = addvararg ( 1, 2, 3, 4, 5, ) ; 

res = addvararg (1,2, 3, 4, 5, 6, 7, 8, 9, 10, 0) ; 

} 
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OPERATORS 

Operators are tokens that trigger some computation when applied to variables and 
other objects in an expression. 

■ Arithmetic Operators 

■ Assignment Operators 

■ Bitwise Operators 

■ Logical Operators 

■ Reference/Indirect Operators 

■ Relational Operators 

■ Structure Member Selectors 

■ Comma Operator , 

■ Conditional Operator? 

■ Array subscript operator [ ] 

■ Function call operator o 

■ sizeof Operator 

■ Preprocessor Operators # and ## 
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Operators Presidence and Associativity 

There are 15 precedence categories, some of them contain only one operator. 
Operators in the same category have equal precedence. 

If duplicates of operators appear in the table, the first occurrence is unary and the 
second binary. Each category has an associativity rule: left-to-right ( —), or right-to- 
left ( «-). In the absence of parentheses, these rules resolve a grouping of expres- 
sions with operators of equal precedence. 



Precedence 


Operands 


Operators 


Associativity 


15 


2 


[ ] 


— 


14 


1 


& (type) sizeof 


- 


13 


2 


/ % 


-> 


12 


2 


+ 


— 


11 


2 


« >> 


-> 


10 


2 


<<=>>= 


— 


9 


2 


! = 


— 


8 


2 




-> 


7 


2 




— 


6 


2 




-> 


5 


2 


&& 


— 


4 


2 




— 


3 


3 


9 ; 


- 


2 


2 


|= <<= >> 


- 


1 


2 


/ 


- 
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Arithmetic Operators 

Arithmetic operators are used to perform mathematical computations. They have 
numerical operands and return numerical results. The type char technically repre- 
sents small integers, so the char variables can be used as operands in arithmetic 
operations. 

All arithmetic operators associate from left to right. 
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Operator 


Operation 


Precedence 


Binary Operators 


+ 


addition 


12 


- 


subtraction 


12 


* 


multiplication 


13 


/ 


division 


13 


% 


modulus operator returns the remainder of integer 
division (cannot be used with floating points) 


13 




Unary Operators 




+ 


unary plus does not affect the operand 


14 


- 


unary minus changes the sign of the operand 


14 


++ 


increment adds one to the value of the operand. 

Postincrement adds one to the value of the operand 

after it evaluates; while preincrement adds one 

before it evaluates 


14 


- 


decrement subtracts one from the value of the 
operand. Postdecrement subtracts one from the 
value of the operand after it evaluates; while pre- 
decrement subtracts one before it evaluates 


14 



Note: Operator * is context sensitive and can also represent the pointer reference 
operator. 
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Binary Arithmetic Operators 

Division of two integers returns an integer, while remainder is simply truncated: 

/* for example: */ 

7/4; /* equals 1 */ 

7*3/4; /* equals 5 */ 

/* but: */ 

7. * 3. / 4.; /* equals 5.25 because we are working with floats */ 

Remainder operand works only with integers; the sign of result is equal to the sign 
of the first operand: 

/* for example: */ 

9 % 3; /* equals 0*7 

7 % 3; /* equals 1 */ 

-7 % 3; /* equals -1 */ 

Arithmetic operators can be used for manipulating characters: 

'A' + 32; /* equals 'a' (ASCII only) */ 

'G' - 'A' + 'a'; /* equals 'g' (both ASCII and EBCDIC) */ 

Unary Arithmetic Operators 

Unary operators ++ and are the only operators in C which can be either prefix 
(e.g. ++k, — k) or postfix (e.g. k++, k — ). 

When used as prefix, operators ++ and -- (preincrement and predecrement) add or 
subtract one from the value of the operand before the evaluation. When used as suf- 
fix, operators ++ and -- (postincrement and postdecrement) add or subtract one 
from the value of the operand after the evaluation. 

For example: 

int j = 5; 

j = ++k; /* k = k + 1, j = k, which gives us j = 6, k=6*/ 

but: 

int j = 5; 

j = k++; /* j = k, k = k + 1, which gives usj=5, k=6*/ 
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Relational Operators 

Use relational operators to test equality or inequality of expressions. If an expres- 
sion evaluates to be true, it returns 1; otherwise it returns 0. 

All relational operators associate from left to right. 

Relational Operators Overview 



Operator 


Operation 


Precedence 


== 


equal 


9 


!= 


not equal 


9 


> 


greater than 


10 


< 


less than 


10 


>= 


greater than or equal 


10 


<= 


less than or equal 


10 



Relational Operators in Expressions 

Precedence of arithmetic and relational operators is designated in such a way to 
allow complex expressions without parentheses to have expected meaning: 



a+5>=c-1.0/e 



/* 



(a + 5) > = 



(1.0 / e) ) */ 



Do not forget that relational operators return either or 1 . Consider the following 
examples: 



/* ok: */ 
5 > 7 
10 <= 20 



/* returns * / 
/* returns 1 * / 



(13 > 5) ? 8 



/* this can be tricky: */ 

8 == 13 > 5 /* returns 0, as: 8 

? */ 

14 > 5 < 3 /* returns 1, as: (14 > 5) < 3 ? 1 < 3 ? 

1 */ 

a < b < 5 /* returns 1, as: (a < b) < 5 ? (0 or 1) 

< 5 ? 1*/ 
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Bitwise Operators 

Use the bitwise operators to modify individual bits of numerical operands. 

Bitwise operators associate from left to right. The only exception is the bitwise com- 
plement operator which associates from right to left. 



Bitwise Operators Overview 



Operator 


Operation 


Precedence 


& 


bitwise AND; compares pairs of bits and returns 1 if 
both bits are 1 , otherwise returns 


8 


1 


bitwise (inclusive) OR; compares pairs of bits and returns 1 if 
either or both bits are 1 , otherwise returns 


6 


A 


bitwise exclusive OR (XOR); compares pairs of bits 
and returns 1 if the bits are complementary, other- 
wise returns 


7 


~ 


bitwise complement (unary); inverts each bit 


14 


« 


bitwise shift left; moves the bits to the left, discards 
the far left bit and assigns to the far right bit. 


11 


» 


bitwise shift right; moves the bits to the right, dis- 
cards the far right bit and if unsigned assigns to 
the far left bit, otherwise sign extends 


11 



Logical Operations on Bit Level 



& 





1 




I 





1 




A 





1 




~ 





1 

















1 








1 




1 





1 





1 


1 


1 


1 


1 


1 














Bitwise operators & , i and ' perform logical operations on the appropriate pairs of bits 
of their operands. Operator complements each bit of its operand. For example: 
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0x1234 s 0x5678 /* equals 0x1230 */ 

/* because . . 

0x1234 : 0001 0010 0011 0100 
0x5678 : 0101 0110 0111 1000 



& : 0001 0010 0011 0000 

. . that is, 0x1230 */ 

/* Similarly: */ 

0x1234 | 0x5678; /* equals 0x567C */ 
0x1234 A 0x5678; /* equals 0x444C */ 
~ 0x1234; /* equals OxEDCB */ 

Note: Operator & can also be a pointer reference operator. Refer to Pointers for 
more information. 

Bitwise Shift Operators 

Binary operators < and move the bits of the left operand by a number of posi- 
tions specified by the right operand, to the left or right, respectively. Right operand 
has to be positive. 

With shift left (<<), far left bits are discarded and "new" bits on the right are assigned 
zeroes. Thus, shifting unsigned operand to the left by n positions is equivalent to 
multiplying it by 2n if all discarded bits are zero. This is also true for signed operands 
if all discarded bits are equal to a sign bit. 



000001 « 5; /* equals 000040 */ 

0x3801 « 4; /* equals 0x8010, overflow! */ 

With shift right (»), far right bits are discarded and the "freed" bits on the left are 
assigned zeroes (in case of unsigned operand) or the value of a sign bit (in case of 
signed operand). Shifting operand to the right by n positions is equivalent to divid- 
ing it by 2n. 



0xFF56 » 4; /* equals 0xFFF5 */ 
0xFF56u » 4; /* equals 0x0FF5 */ 
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Bitwise versus Logical 



Do not forget of the principle difference between how bitwise and logical operators 
work. For example: 



0222222 & 0555555; 
0222222 && 0555555; 

~ 0x1234; 
! 0x1234; 



/* equals 000000 */ 

/* equals 1 */ 

/* equals OxEDCB */ 

/* equals * / 



Logical Operators 

Operands of logical operations are considered true or false, that is non-zero or zero. 
Logical operators always return 1 or 0. Operands in a logical expression must be of 
scalar type. 

Logical operators && and | associate from left to right. Logical negation operator ! 
associates from right to left. 

Logical Operators Overview 



Operator 


Operation 


Precedence 


&& 


logical AND 


5 


II 


logical OR 


4 


! 


logical negation 


14 



Logical Operators 



&& 





X 




II 





X 




! 





X 

















1 




1 





X 





1 


X 


1 


1 











Precedence of logical, relational, and arithmetic operators was designated in such 
a way to allow complex expressions without parentheses to have an expected 
meaning: 



c >= '0' && c <= '9'; 

a + 1 == b II ! f (x) ; 



/* reads as: (c >= '0') && (c <= '9') */ 

/* reads as: ( (a + 1) == b) || (! (f(x))) */ 



Logical AND ss returns 1 only if both expressions evaluate to be nonzero, otherwise 
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returns 0. If the first expression evaluates to false, the second expression will not be 
evaluated. For example: 

a > b SS c < d; /* reads as (a > b) SS (c < d) */ 

/* if (a > b) is false (0), (c < d) will not be evaluated */ 

Logical OR i ! returns 1 if either of expression evaluates to be nonzero, otherwise 
returns 0. If the first expression evaluates to true, the second expression is not eval- 
uated. For example: 

a SS b || c SS d; /* reads as: (a ss b) II (c SS d) */ 

/* if (a SS b) is true (1), (c SS d) will not be evaluated */ 

Logical Expressions and Side Effects 

General rule regarding complex logical expressions is that the evaluation of consec- 
utive logical operands stops at the very moment the final result is known. For exam- 
ple, if we have an expression a ss b ss c where a is false (0), then operands b 
and : will not be evaluated. This is very important if b and □ are expressions, as their 
possible side effects will not take place! 

Logical versus Bitwise 

Be aware of the principle difference between how bitwise and logical operators 
work. For example: 

0222222 s 0555555 /* equals 000000 */ 
0222222 SS 0555555 /* equals 1 */ 

~ 0x1234 /* equals OxEDCB */ 

! 0x1234 /* equals */ 
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Conditional Operator ? : 

The conditional operator ? : is the only ternary operator in C. Syntax of the condi- 
tional operator is: 

expressionl ? expression2 : expressions 

The expressionl is evaluated first. If its value is true, then expression2 evaluates 
and expressions is ignored. If expressionl evaluates to false, then expressions 
evaluates and expression2 is ignored. The result will be a value of either expres- 
sion2 or expressions depending upon which of them evaluates. 

Note: The fact that only one of these two expressions evaluates is very important if 
they are expected to produce side effects! 

Conditional operator associates from right to left. 
Here are a couple of practical examples: 

/* Find max (a, b) : * / 
max = ( a > b ) ? a : b; 

/* Convert small letter to capital: */ 

/* (no parentheses are actually necessary) */ 

c = ( c >= 'a' && c <= 'z ' ) ? ( c - 32 ) : c; 

Conditional Operator Rules 

expressionl must be a scalar expression; expression2 and expressions must 
obey one of the following rules: 

1. Both expressions have to be of arithmetic type. expression2 and expressions 
are subject to usual arithmetic conversions, which determines the resulting type. 

2. Both expressions have to be of compatible struct or union types. The resulting 
type is a structure or union type of expression2 and expressions. 

3. Both expressions have to be of void type. The resulting type is void. 

4. Both expressions have to be of type pointer to qualified or unqualified versions 
of compatible types. The resulting type is a pointer to a type qualified with all type 
qualifiers of the types pointed to by both expressions. 

5. One expression is a pointer, and the other is a null pointer constant. The result- 
ing type is a pointer to a type qualified with all type qualifiers of the types point- 
ed to by both expressions. 

6. One expression is a pointer to an object or incomplete type, and the other is a 
pointer to a qualified or unqualified version of void. The resulting type is that of 
the non-pointer-to-void expression. 
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Assignment Operators 

Unlike many other programming languages, C treats value assignment as operation 
(represented by an operator) rather than instruction. 

Simple Assignment Operator 

For a common value assignment, a simple assignment operator (=) is used: 

expressionl=expression2 

The expressioni is an object (memory location) to which the value of expression 
is assigned. Operand expressioni has to be lvalue and expression can be any 
expression. The assignment expression itself is not lvalue. 

If expressioni and expression2 are of different types, the result Of the expres- 

sion2 will be converted to the type of expressioni, if necessary. Refer to Type 
Conversions for more information. 

Compound Assignment Operator 

C allows more comlex assignments by means of compound assignment operators. 
The syntax of compound assignment operators is: 

expressioni op = expression2 

where op can be one of binary operators +, -, *, /, %, s, |, A , «, or ». 

Thus, we have 10 different compound assignment operators: +=, -=, * = , /=, %=, 
&=, |=, =, «== and »=. All of them associate from right to left. Spaces sepa- 
rating compound operators (e.g. +=) will generate an error. 

Compound assignment has the same effect as 

expressioni = expressioni op expression2 

except the lvalue expressioni is evaluated only once. For example, expres- 

sionl + = expression2 is the same as expressioni = expressioni + expres- 
sion2. 
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Assignment Rules 

For both simple and compound assignment, the operands expressioni and 
expression must obey one of the following rules: 

1 . expressioni is of qualified or unqualified arithmetic type and expression is of 
arithmetic type. 

2. expressioni has a qualified or unqualified version of structure or union type 
compatible with the type of expression2. 

3. expressioni and expression2 are pointers to qualified or unqualified versions 
of compatible types and the type pointed to by left has all qualifiers of the type 
pointed to by right. 

4. Either expressioni or expression2 is a pointer to an object or incomplete type 
and the other is a pointer to a qualified or unqualified version of void. The type 
pointed to by left has all qualifiers of the type pointed to by right. 

5. expressioni is a pointer and expression2 is a null pointer constant. 

Sizeof Operator 

The prefix unary operator sizeof returns an integer constant that represents the 
size of memory space (in bytes) used by its operand (determined by its type, with 
some exceptions). 

The operator sizeof can take either a type identifier or an unary expression as an 
operand. You cannot use sizeof with expressions of function type, incomplete types, 
parenthesized names of such types, or with lvalue that designates a bit field object. 

Sizeof Applied to Expression 

If applied to expression, the size of an operand is determined without evaluating the 
expression (and therefore without side effects). The result of the operation will be 
the size of the type of the expression's result. 

Sizeof Applied to Type 

If applied to a type identifier, sizeof returns the size of the specified type. The unit 
for type size is sizeof (char) which is equivalent to one byte. The operation size- 
of (char) gives the result 1 , Whether char is signed Or unsigned. 

Thus: 



sizeof (char) 


/* 


returns 


1 


*/ 


sizeof (int) 


/* 


returns 


2 


*/ 


sizeof (unsigned long) 


/* 


returns 


4 


*/ 


sizeof (float) 


/* 


returns 


4 


*/ 
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When the operand is a non-parameter of array type, the result is the total number of 
bytes in the array (in other words, an array name is not converted to a pointer type): 

int i, j , a[ 10] ; 

j = sizeof(a[ 1] ) ; /* j = sizeof (int) = 2 */ 

i = sizeof (a); /* i = 10* sizeof (int ) = 20 */ 

/* To get the number of elements in an array: */ 
int num elem = i/j ; 

If the operand is a parameter declared as array type or function type, sizeof gives 
the size of the pointer. When applied to structures and unions, sizeof gives the 
total number of bytes, including any padding. The operator sizeof cannot be 
applied to a function. 



EXPRESSION 

Expression is a sequence of operators, operands, and punctuators that specifies a 
computation. Formally, expressions are defined recursively: subexpressions can be 
nested without formal limit. However, the compiler will report an out-of-memory error 
if it can't compile an expression that is too complex. 

In ANSI C, the primary expressions are: constant (also referred to as literal), identi- 
fier, and (expression), defined recursively. 

Expressions are evaluated according to a certain conversion, grouping, associativi- 
ty and precedence rules, which depends on the operators used, presence of paren- 
theses and data types of the operands. The precedence and associativity of the 
operators are summarized in Operator Precedence and Associativity. The way 
operands and subexpressions are grouped does not necessarily specify the actual 
order in which they are evaluated by the mikroC PRO for PIC. 

Expressions can produce lvalue, rvalue, or no value. Expressions might cause side 
effects whether they produce a value or not. 

Comma Expressions 

One of the specifics of C is that it allows using of comma as a sequence operator to 
form so-called comma expressions or sequences. Comma expression is a comma- 
delimited list of expressions - it is formally treated as a single expression so it can 
be used in places where an expression is expected. The following sequence: 

expression 1, expression 2; 
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results in the left-to-right evaluation of each expression, with the value and type of 
expression 2 giving the result of the whole expression. Result of expression 1 
is discarded. 

Binary operator comma (,) has the lowest precedence and associates from left to 
right, so that a, b, c is the same as (a, b) , c. This allows writing sequences 
with any number of expressions: 

expression 1, expression 2, ... expression n; 

which results in the left-to-right evaluation of each expression, with the value and 
type of expression n giving the result of the whole expression. Results of other 
expressions are discarded, but their (possible) side-effect do occur. 

For example: 

result = ( a = 5, b /= 2, C++ ) ; 

/* returns preincremented value of variable c, 

but also intializes a, divides b by 2 and increments c */ 

result = ( x = 10, y = x + 3, x--, z -= x * 3 - --y ) ; 

/* returns computed value of variable z, 
and also computes x and y */ 

Note 

Do not confuse comma operator (sequence operator) with comma punctuator which 
separates elements in a function argument list and initializator lists. To avoid ambi- 
guity with commas in function argument and initializer lists, use parentheses. For 
example, 

func (i, ( j = 1, j + 4) , k) ; 

calls the function func with three arguments (i, 5, k), not four. 
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STATEMENTS 

Statements specify a flow of control as the program executes. In the absence of 
specific jump and selection statements, statements are executed sequentially in the 
order of appearance in the source code. 

Statements can be roughly divided into: 

- Labeled Statements 

- Expression Statements 

- Selection Statements 

- Iteration Statements (Loops) 

- Jump Statements 

- Compound Statements (Blocks) 

Labeled Statements 

Each statement in a program can be labeled. A label is an identifier added before 
the statement like this: 

label_identif ier : statement; 

There is no special declaration of a label - it just "tags" the statement, label iden- 
tifier has a function scope and the same label cannot be redefined within the 
same function. 

Labels have their own namespace: label identifier can match any other identifier in 
the program. 



A statement can be labeled for two reasons: 

1 . The label identifier serves as a target for the unconditional goto statement, 

2. The label identifier serves as a target for the switch statement. For this purpose, 
only case and default labeled statements are used: 

case constant-expression : statement 
default : statement 
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Expression Statements 

Any expression followed by a semicolon forms an expression statement: 

expression; 

The mikroC PRO for PIC executes an expression statement by evaluating the 
expression. All side effects from this evaluation are completed before the next 
statement starts executing. Most of expression statements are assignment state- 
ments or function calls. 

A null statement is a special case, consisting of a single semicolon (,■ ). The null 
statement does nothing, and therefore is useful in situations where the mikroC PRO 
for PIC syntax expects a statement but the program does not need one. For exam- 
ple, a null statement is commonly used in "empty" loops: 

for ( ; *q++ = *p++ ;); /* body of this loop is a null statement */ 

Selection Statements 

Selection or flow-control statements select one of alternative courses of action by 
testing certain values. There are two types of selection statements: 

■ if 

■ switch 

If Statement 

The if statement is used to implement a conditional statement. The syntax of the 
if statement is: 

if (expression) statementl [ else statement2] 

If expression evaluates tO true, statementl executes. If statement is false, 

statement2 executes. The expression must evaluate to an integral value; other- 
wise, the condition is ill-formed. Parentheses around the expression are mandato- 
ry. 

The else keyword is optional, but no statements can come between if and else. 
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Nested If Statement 

Nested if statements require additional attention. A general rule is that the nested 
conditionals are parsed starting from the innermost conditional, with each else 
bound to the nearest available if on its left: 

if (expressionl ) statementl 
else if (expression2 ) 

if (expression3 ) statement2 

else statements /* this belongs to: if (expression3) */ 
else statement4 /* this belongs to: if (expression2 ) */ 

Note 

#if and #eise preprocessor statements (directives) look similar to if and else 
statements, but have very different effects. They control which source file lines are 
compiled and which are ignored. 

Switch Statements 

The switch statement is used to pass control to a specific program branch, based 
on a certain condition. The syntax of the switch statement is: 

switch (expression) { 

case constant-expression_l : statement 1; 



case constant-expression n : statement n; 
[default : statement;] 



First, the expression (condition) is evaluated. The switch statement then com- 
pares it to all available constant-expressions following the keyword case. If a match 
is found, switch passes control to that matching case causing the statement fol- 
lowing the match evaluates. Note that constant-expressions must evaluate to 
integer. It is not possible to have two same constant expressions evaluating to 
the same value. 

Parentheses around expression are mandatory. 

Upon finding a match, program flow continues normally: the following instructions 
will be executed in natural order regardless of the possible case label. If no case 
satisfies the condition, the default case evaluates (if the label default is speci- 
fied). 
For example, if a variable i has value between 1 and 3, the following switch would 
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always return it as 4: 



switch 


(i 


) { 


case 


1 


i++; 


case 


2 


i++; 


case 


3 


i++; 



To avoid evaluating any other cases and relinquish control from switch, each case 
should be terminated with break. 

Here is a simple example with switch. Suppose we have a variable phase with only 
3 different states (0, 1 , or 2) and a corresponding function (event) for each of these 
states. This is how we could switch the code to the appopriate routine: 

switch (phase) { 

case 0: Lo(); break; 

case 1: Mid(); break; 

case 2: Hi(); break; 

case: Message ( "Invalid state!"); 
} 

Nested Switch 

Conditional switch statements can be nested- labels case and default are then 
assigned to the innermost enclosing switch statement. 

Iteration Statements (Loops) 

Iteration statements allows to loop a set of statements. There are three forms of iter- 
ation statements in the mikroC PRO for PIC: 

■ while 

■ do 

■ for 

While Statement 

The while keyword is used to conditionally iterate a statement. The syntax of the 
while statement is: 

while (expression) statement 

The statement executes repeatedly until the value of expression is false. The test 
takes place before statement is executed. Thus, if expression evaluates to false 
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on the first pass, the loop does not execute. Note that parentheses around expres- 
sion are mandatory. 

Here is an example of calculating scalar product of two vectors, using the while 
statement: 

int s = 0, i = 0; 
while (i < n) { 

s += a[ i] * b[ i] ; 
i++; 



Note that body of the loop can be a null statement. For example: 

while (*q++ = *p++) ; 

Do Statement 

The do statement executes until the condition becomes false. The syntax of the do 
statement is: 

do statement while (expression); 

The statement is executed repeatedly as long as the value of expression remains 
non-zero. The expression is evaluated after each iteration, so the loop will execute 
statement at least once. 

Parentheses around expression are mandatory. 

Note that do is the only control structure in C which explicitly ends with semicolon 
(,). Other control structures end with statement, which means that they implicitly 
include a semicolon or closing brace. 

Here is an example of calculating scalar product of two vectors, using the do state- 
ment: 

s = 0; i = 0; 
do { 

s += a[ i] * b[ i] ; 

i + +; 
} while ( i < n ) ; 
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For Statement 

The for statement implements an iterative loop. The syntax of the for statement 
is: 

for ([ init-expression] ; [ condition-expression] ; [ increment-expres- 
sion] ) statement 

Before the first iteration of the loop, init-expression sets the starting variables for 
the loop. You cannot pass declarations in init-expression. 

condition-expression is checked before the first entry into the block; statement 
is executed repeatedly until the value of condition-expression is false. After 
each iteration of the loop, increment-expression increments a loop counter. Conse- 
quently, :t^ is functionally the same as ++i. 

All expressions are optional. If condition-expression is left out, it is assumed to 
be always true. Thus, "empty" for statement is commonly used to create an end- 
less loop in C: 

for ( ; ; ) statement 

The only way to break out of this loop is by means of the break statement. 

Here is an example of calculating scalar product of two vectors, using the for state- 
ment: 

for ( s = 0, i = 0;i<n; i++ ) s += a[ i] * b[ i] ; 

There is another way to do this: 

for ( s = 0, i = 0; i < n; s += a[ i] * b[ i] , i + + ) ; /* valid, but 
ugly * / 

but it is considered a bad programming style. Although legal, calculating the sum 
should not be a part of the incrementing expression, because it is not in the service 
of loop routine. Note that null statement (;) is used for the loop body. 
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Jump Statements 

The jump statement, when executed, transfers control unconditionally. There are 
four such statements in the mikroC PRO for PIC: 

■ break 

■ continue 

■ goto 

■ return 

BREAK AND CONTINUE STATEMENTS 
Break Statement 

Sometimes it is necessary to stop the loop within its body. Use the break statement 
within loops to pass control to the first statement following the innermost switch, 

for, while, Or do block. 

break is commonly used in the switch statements to stop its execution upon the 
first positive match. For example: 

switch (state) { 



case : 


Lo ( ) ; 


break; 


case 1 : 


Mid ( ) ; 


break; 


case 2 : 


Hi ( ) ; 


break; 



default: Message ("Invalid state!"); 
} 

Continue Statement 

The continue statement within loops is used to "skip the cycle". It passes control 
to the end of the innermost enclosing end brace belonging to a looping construct. At 
that point the loop continuation condition is re-evaluated. This means that contin- 
ue demands the next iteration if the loop continuation condition is true. 

Specifically, the continue statement within the loop will jump to the marked posi- 
tion as it is shown below: 

while ( . . ) { do { for (..;..;..) { 

if (val>0) continue; if (val>0) continue; if (val>0) continue; 

// continue jumps // continue jumps // continue jumps 
here here here 

} while ( . . ) ; } 
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Goto Statement 

The goto statement is used for unconditional jump to a local label — for more infor- 
mation on labels, refer to Labeled Statements. The syntax of the goto statement is: 

goto label_identif ier ; 

This will transfer control to the location of a local label specified by label identi- 
fier. The label identifier has to be a name of the label within the same func- 
tion in which the goto statement is. The goto line can come before or after the label. 

goto is used to break out from any level of nested control structures but it cannot be 
used to jump into block while skipping that block's initializations - for example, jump- 
ing into loop's body, etc. 

The use of goto statement is generally discouraged as practically every algorithm can 
be realized without it, resulting in legible structured programs. One possible application 
of the goto statement is breaking out from deeply nested control structures: 

for (...) { 
for (...) { 

if (disaster) goto Error; 



Error: /* error handling code */ 

Return Statement 

The return statement is used to exit from the current function back to the calling 
routine, optionally returning a value. The syntax is: 

return [ expression] ; 

This will evaluate expression and return the result. Returned value will be auto- 
matically converted to the expected function type, if needed. The expression is 
optional; if omitted, the function will return a random value from memory. 

Note: The statement return in functions of the void type cannot have expres- 
sion - in fact, the return statement can be omitted altogether if it is the last state- 
ment in the function body. 
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Compound Statements (Blocks) 

The compound statement, or block, is a list (possibly empty) of statements enclosed 
in matching braces { }. Syntactically, the block can be considered to be a single 
statement, but it also plays a role in the scoping of identifiers. An identifier declared 
within the block has a scope starting at the point of declaration and ending at the 
closing brace. Blocks can be nested to any depth up to the limits of memory. 

For example, the for loop expects one statement in its body, so we can pass it a 
compound statement: 

for (i = 0; i < n; i++ ) { 
int temp = a[ i] ; 
a[ i] = b[ i] ; 
b[ i] = temp; 

} 

Note that, unlike other statements, compound statements do not end with semicolon 
(,), i.e. there is never a semicolon following the closing brace. 

PREPROCESSOR 

Preprocessor is an integrated text processor which prepares the source code for 
compiling. Preprocessor allows: 

- inserting text from a specifed file to a certain point in the code (see File Inclusion), 

- replacing specific lexical symbols with other symbols (see Macros), 

- conditional compiling which conditionally includes or omits parts of the code (see 
Conditional Compilation). 

Note that preprocessor analyzes text at token level, not at individual character level. 
Preprocessor is controled by means of preprocessor directives and preprocessor 
operators. 

Preprocessor Directives 

Any line in the source code with a leading a is taken as a preprocessing directive (or 
control line), unless s is within a string literal, in a character constant, or embedded 
in a comment. The initial » can be preceded or followed by a whitespace (excluding 
new lines). 

A null directive consists of a line containing the single character #. This line is always 
ignored. 

Preprocessor directives are usually placed at the beginning of the source code, but 
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they can legally appear at any point in a program. The mikroC PRO for PIC pre- 
processor detects preprocessor directives and parses the tokens embedded in 
them. A directive is in effect from its declaration to the end of the program file. 

Here is one commonly used directive: 

#include <math.h> 

For more information on including files with the #inciude directive, refer to File 
Inclusion. 

The mikroC PRO for PIC supports standard preprocessor directives: 



# (null 


direc 


t 


ive) 


#if 


#def ine 








tifdef 


felif 








fifndef 


♦ else 








#include 


#endif 








fline 


terror 








#undef 



Note: For the time being only funcall pragma is supported. 
Line Continuation with Backslash (\) 

To break directive into multiple lines end the line with a backslash (\): 

#define MACRO This directive continues to \ 
the following line. 
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Macros 

Macros provide a mechanism for a token replacement, prior to compilation, with or 
without a set of formal, function-like parameters. 

Defining Macros and Macro Expansions 

The #define directive defines a macro: 

#define macro_identif ier <token sequence> 

Each occurrence of macro_identif ier in the source code following this control line will 
be replaced in the original position with the possibly empty token sequence (there are 
some exceptions, which are discussed later). Such replacements are known as macro 
expansions. token sequence is sometimes called the body of a macro. An empty token 
sequence results in the removal of each affected macro identifier from the source code. 

No semicolon (;) is needed to terminate a preprocessor directive. Any character 
found in the token sequence, including semicolons, will appear in a macro expan- 
sion. token sequence terminates at the first non-backslashed new line encoun- 
tered. Any sequence of whitespace, including comments in the token sequence, is 
replaced with a single-space character. 

After each individual macro expansion, a further scan is made of the newly expanded 
text. This allows the possibility of using nested macros: the expanded text can contain 
macro identifiers that are subject to replacement. However, if the macro expands into 
something that looks like a preprocessing directive, such directive will not be recog- 
nized by the preprocessor. Any occurrences of the macro identifier found within literal 
strings, character constants, or comments in the source code will not be expanded. 

A macro won't be expanded during its own expansion (so #def ine macro macro 
won't expand indefinitely). 
Here is an example: 

/* Here are some simple macros: */ 
#define ERR_MSG "Out of range!" 
#define EVERLOOP f or ( ; ; ) 
/* which we could use like this: */ 
main ( ) { 

EVERLOOP { 

if (error) { Lcd_Out_Cp (ERR_MSG) ; break; } 
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Attempting to redefine an already defined macro identifier will result in a warning 
unless a new definition is exactly the same token-by-token definition as the existing 
one. The preferred strategy when definitions might exist in other header files is as 
follows: 

#ifndef BLOCK_SIZE 

#define BLOCK_SIZE 512 
#endif 

The middle line is bypassed if blocksize is currently defined; if blocksize is 
not currently defined, the middle line is invoked to define it. 

Macros with Parameters 

The following syntax is used to define a macro with parameters: 

#define macro identifier (<arg list>) <token sequence> 

Note that there can be no whitespace between macro identifier and " (". The 
optional arg list is a sequence of identifiers separated by commas, like the argu- 
ment list of a C function. Each comma-delimited identifier has the role of a formal 
argument or placeholder. 

Such macros are called by writing 

macro identifier (<actual arg list>) 

in the subsequent source code. The syntax is identical to that of a function call; 
indeed, many standard library C "functions" are implemented as macros. However, 
there are some important semantic differences. 

The optional actual arg list must contain the same number of comma-delimit- 
ed token sequences, known as actual arguments, as found in the formal argjist of 
the #def ine line - there must be an actual argument for each formal argument. An 
error will be reported if the number of arguments in two lists is not the same. 

A macro call results in two sets of replacements. First, the macro identifier and the 
parenthesis-enclosed arguments are replaced by the token sequence. Next, any for- 
mal arguments occurring in the token sequence are replaced by the corresponding 
real arguments appearing in actual arg list. Like with simple macro definitions, 
rescanning occurs to detect any embedded macro identifiers eligible for expansion. 

Here is a simple example: 

/* A simple macro which returns greater of its 2 arguments: */ 
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#define _MAX (A, B) ((A) > (B) ) ? (A) : (B) 

/* Let's call it: */ 

x = _MAX(a + b, c + d) ; 

/* Preprocessor will transform the previous line into: 
x = ( (a + b) > (c + d) ) ? (a + b) : (c + d) */ 

It is highly recommended to put parentheses around each argument in the macro 
body in order to avoid possible problems with operator precedence. 

Undefining Macros 

The lundef directive is used to undefine a macro. 

#undef macro identifier 

The directive #undef detaches any previous token sequence from macro identi- 
fier; the macro definition has been forgotten, and macro identifier is undefined. 
No macro expansion occurs within the #undef lines. 

The state of being defined or undefined is an important property of an identifier, 
regardless of the actual definition. The #ifdef and #ifndef conditional directives, 
used to test whether any identifier is currently defined or not, offer a flexible mech- 
anism for controlling many aspects of a compilation. 

After a macro identifier has been undefined, it can be redefined with #def ine, using 
the same or different token sequence. 

File Inclusion 

The preprocessor directive # include pulls in header files (extension .h) into the 
source code. Do not rely on preprocessor to include source files (extension ) — see 
Add/Remove Files from Project for more information. 

The syntax of the # include directive has two formats: 

#include <header name> 
#include "header name" 

The preprocessor removes the #inciude line and replaces it with the entire text of 
a header file at that point in the source code. The placement of # include can there- 
fore influence the scope and duration of any identifiers in the included file. 

The difference between these two formats lies in searching algorithm employed in 
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trying to locate the include file. 

If the finciude directive is used with the <header_name> version, the search is 
made successively in each of the following locations, in this particular order: 

1. the mikroC PRO for PIC installation folder > "include" folder 

2. user's custom search paths 

The "header name" version specifies a user-supplied include file; the mikroC PRO 
for PIC will look for the header file in the following locations, in this particular order: 

1 . the project folder (folder which contains the project file .mcppi) 

2. the mikroC PRO for PIC installation folder > "include" folder 

3. user's custom search paths 

Explicit Path 

By placing an explicit path in header name, only that directory will be searched. For 
example: 

#include "C:\my_files\test.h" 

Note 

There is also a third version of the #inciude directive, rarely used, which assumes 
that neither nor " appear as the first non-whitespace character following 

#include! 

#include macro identifier 

It assumes that macro definition that will expand macro identifier into a valid 
delimited header name with either <header name> or "header name" formats 
exists. 
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Preprocessor Operators 

The # (pound sign) is a preprocessor directive when it occurs as the first non-white- 
space character on a line. Also, # and ## perform operator replacement and merg- 
ing during the preprocessor scanning phase. 

Operator # 

In C preprocessor, a character sequence enclosed by quotes is considered a token 
and its content is not analyzed. This means that macro names within quotes are not 
expanded. 

If you need an actual argument (the exact sequence of characters within quotes) as 
a result of preprocessing, use the s operator in macro body. It can be placed in front 
of a formal macro argument in definition in order to convert the actual argument to 
a string after replacement. 

For example, let's have macro lcd print for printing variable name and value on 
Led: 

#define LCD_PRINT (val) Lcd_Custom_Out_Cp (#val ": "); \ 

Lcd_Custom_Out_Cp (IntToStr (val) ) ; 

Now, the following code, 

LCD_PRINT(temp) 

will be preprocessed to this: 

Lcd_Custom_Out_Cp ( "temp" ": " ) ; Lcd_Custom_Out_Cp (IntToStr (temp) ) ; 

Operator ## 

Operator s <• is used for token pasting. Two tokens can be pasted(merged) together 
by placing s# in between them (plus optional whitespace on either side). The pre- 
processor removes whitespace and s » , combining the separate tokens into one new 
token. This is commonly used for constructing identifiers. 

For example, see the definition of macro splice for pasting two tokens into one 
identifier: 

#define SPLICE (x,y) x ## __ ## y 

Now, the call splice (cnt, 2) will expand to the identifier cnt_2. 
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Note 

The mikroC PRO for PIC does not support the older nonportable method of token 
pasting using (i/**/r) . 

Conditional Compilation 

Conditional compilation directives are typically used to make source programs easy 
to change and easy to compile in different execution environments. The mikroC 
PRO for PIC supports conditional compilation by replacing the appropriate source- 
code lines with a blank line. 

All conditional compilation directives must be completed in the source or include file 
in which they have begun. 

Directives #if, #elif, #else and #endif 

The conditional directives #if, #eiif, #eise, and #endif work very similar to 
the common C conditional statements. If the expression you write after #if has a 
nonzero value, the line group immediately following the ; if directive is retained in 
the translation unit. 

The syntax is: 

#if constant expression 1 
<section 1> 

[ #elif constant expression 2 
<section 2>] 

[ #elif constant_expression n 
<section n>] 

[ #else 

<final section>] 

#endif 

Each #if directive in a source file must be matched by a closing #endif directive. 
Any number of #eiif directives can appear between l and #endif directives, but 
at most one leise directive is allowed. The teise directive, if present, must be the 
last directive before #endif. 

sections can be any program text that has meaning to compiler or preprocessor. 
The preprocessor selects a single section by evaluating constant expression fol- 
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lowing each #if or #eiif directive until it finds a true (nonzero) constant expres- 
sion. The constant expressions are subject to macro expansion. 

If all occurrences of constant-expression are false, or if no #eiif directives appear, 
the preprocessor selects the text block after the #eise clause. If the #eise clause 
is omitted and all instances of constant expression in the #if block are false, no 
section is selected for further processing. 

Any processed section can contain further conditional clauses, nested to any depth. 
Each nested leise, #eiif, or #endif directive belongs to the closest preceding 
the #if directive. 

The net result of the preceding scenario is that only one code section (possibly 
empty) will be compiled. 

Directives #ifdef and #ifndef 

The #ifdef and #ifndef directives can be used anywhere #if can be used and 
they can test whether an identifier is currently defined or not. The line 

#ifdef identifier 

has exactly the same effect as #if 1 if identifier is currently defined, and the 
same effect as #if o if identifier is currently undefined. The other directive, 
tifndef, tests true for the "not-defined" condition, producing the opposite results. 

The syntax thereafter follows that of #if, #eiif, #eise, and #endif. 

An identifier defined as null is considered to be defined. 
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mikroC PRO for PIC provides a set of libraries which simplify the initialization and 
use of PIC compliant MCUs and their modules: 

Use Library manager to include mikroC PRO for PIC Libraries in you project. 
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Hardware PIC-specific Libraries 

-ADC Library 

- CAN Library 

- CANSPI Library 

- Compact Flash Library 

- EEPROM Library 

- Ethernet PIC18FxxJ60 Library 

- Flash Memory Library 

- Graphic LCD Library 

- PC Library 

- Keypad Library 

- LCD Library 

- Manchester Code Library 

- Muliti Media Card Libray 

- OneWire Library 

- Port Expander Library 

- Printout Library 

- PS/2 Library 

- PWM Library 

- RS-485 Library 

- Software PC Library 

- Software SPI Library 

- Software UART Library 

- Sound Library 

- SPI Library 

- SPI Ethernet Library 

- SPI Graphic LCD Library 

- SPI LCD Library 

- SPI LCD8 Library 

- SPI T6963C Graphic LCD Library 

- T6963C Graphic LCD Library 

- UART Library 

- USB HID Library 

Standard ANSI C Libraries 

-ANSI C Ctype Library 
-ANSI C Math Library 
-ANSI CStdlib Library 
-ANSI C String Library 

Miscellaneous Libraries 

- Button Library 

- Conversions Library 

- Sprint Library 

- Setjmp Library 

- Time Library 

- Trigonometry Library 

See also Built-in Routines. 
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LIBRARY DEPENDENCIES 



fCANSPI - | SPI 



[CF_FAT16 



[Conversions 



[GlctT 



| Led 



MMC 



[MMC_FAT16 



[ RS-485 



[SPIEthernot 



[ 5PI_Glcd 



I C_Type 



CompactFlash 



J *- | C_String~ 



*■ Glcd_Fonts 



~1 ^JLcd_Constants 



*[SPI 



* \ C_Type 



[ Port_Expander 



* MMC 



] - | UART 



* String 



J 



^w \ Port_Expander | - 

^[ Glcd_Fonls ~~| 



| SPI Led 




| SPI_LcdS 






[ SPI_T6963C 






| Sprintf 


I- 




| Sprintl 




fSprinti 




[T6963C 



^» ^Port_Expander »- [SPI 



"*[Lcd_Constants 



[ PortExpandeir 



N 



Lcd_Constants 



PortExpander 



*j_Trigonometry 



] >• [ CJType 



C_Type 



r ~C_Type 



*-\ Trigonometry 



Certain libraries use (depend on) 
function and/or variables, con- 
stants defined in other libraries. 
Image below shows clear repre- 
sentation about these dependen- 
cies. 

For example, SPIGIcd uses 
Glcd_Fonts and PortExpander 
library which uses SPI library. 
This means that if you check 
SPI_Glcd library in Library manag- 
er, all libraries on which it depends 
will be checked too. 



Related topics: Library manager, 
PIC Libraries 
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HARDWARE LIBRARIES 

-ADC Library 

- CAN Library 

- CANSPI Library 

- Compact Flash Library 

- EEPROM Library 

- Ethernet PIC18FxxJ60 Library 

- Flash Memory Library 

- Graphic Led Library 

- I L C Library 

- Keypad Library 

- Led Library 

- Manchester Code Library 

- Multi Media Card Library 

- OneWire Library 

- Port Expander Library 

- Printout Library 

- PS/2 Library 

- PWM Library 

- RS-485 Library 

- Software l L C Library 

- Software SPI Library 

- Software UART Library 

- Sound Library 

- SPI Library 

- SPI Ethernet Library 

- SPI Graphic Led Library 

- SPI Led Library 

- SPI Lcd8 Library 

- SPI T6963C Graphic Led Library 

- T6963C Graphic Led Library 

- UART Library 

- USB HID Library 
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ADC LIBRARY 

ADC (Analog to Digital Converter) module is available with a number of PIC MCU models. Library 
function adc Read is included to provide you comfortable work with the module. 

ADC Read 



Prototype 


unsigned ADC Read (unsigned short channel); 


Returns 


10-bit unsigned value read from the specified channel. 


Description 


Initializes PIC's internal ADC module to work with RC clock. Clock determines 
the time period necessary for performing AD conversion (min 12TAD). 

Parameter channel represents the channel from which the analog value is to be 
acquired. Refer to the appropriate datasheet for channel-to-pin mapping. 


Requires 


Nothing. 


Example 


unsigned tmp; 

tmp = ADC Read (2) ; // Read analog value from channel 2 



Library Example 

This example code reads analog value from channel 2 and displays it on PORTB and PORTC. 

unsigned int tempres; 



void main ( ) { 

ANSEL = 0x04; 
TRISA = OxFF; 
ANSELH = 0; 
TRISC = 0x3F; 
TRISB = 0; 



// Configure AN2 pin as analog 

// PORTA is input 

// Configure other AN pins as digital I/O 

// Pins RC7, RC6 are outputs 

// PORTB is output 



do { 

temp_res = ADC_Read(2) 
PORTB = temp_res; 
PORTC = temp_res » 2; 
} while ( 1 ) ; 



// Get 10-bit results of AD conversion 

// Send lower 8 bits to PORTB 

// Send 2 most significant bits to RC7, RC6 
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HW Connection 




ADC HW connection 

CAN LIBRARY 

mikroC PRO for PIC provides a library (driver) for working with the CAN module. 

CAN is a very robust protocol that has error detection and signalling, self-checking 
and fault confinement. Faulty CAN data and remote frames are re-transmitted auto- 
matically, similar to the Ethernet. 

Data transfer rates vary from up to 1 Mbit/s at network lengths below 40m to 250 
Kbit/s at 250m cables, and can go even lower at greater network distances, down 
to 200Kbit/s, which is the minimum bitrate defined by the standard. Cables used are 
shielded twisted pairs, and maximum cable length is 1000m. 

CAN supports two message formats: 

■ Standard format, with 11 identifier bits, and 

■ Extended format, with 29 identifier bits 

Note: CAN Library is supported only by MCUs with the CAN module. 
Note: Consult the CAN standard about CAN bus termination resistance. 
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Library Routines 

■ CANSetOperationMode 

■ CANGetOperationMode 

■ CANInitialize 

■ CANSetBaudRate 

■ CANSetMask 

■ CANSetFilter 

■ CAN Read 

■ CANWrite 

Following routines are for the internal use by compiler only: 

■ RegsToCANID 

■ CANIDToRegs 

Be sure to check CAN constants necessary for using some of the functions. 
CANSetOperationMode 



Prototype 


void CANSetOperationMode (unsigned short mode, unsigned short 

wait flag) ; 


Returns 


Nothing. 


Description 


Sets CAN to requested mode, i.e. copies mode to CANSTAT. Parameter mode 
needs to be one of can op mode constants (see CAN constants). 

Parameter wait flag needs to be either or OxFF: 

■ If set to OxFF, this is a blocking call - the function won't "return" until the 
requested mode is set. 

■ If 0, this is a non-blocking call. It does not verify if CAN module is switched to 
requested mode or not. Caller must use CANGetOperationMode to verify cor- 
rect operation mode before performing mode specific operation. 


Requires 


CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcon- 
troller must be connected to CAN transceiver (MCP2551 or similar) which is 
connected to CAN bus. 


Example 


CANSetOperationMode ( CAN MODE CONFIG, OxFF); 
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CANGetOperationMode 



Prototype 


unsigned short CANGetOperationMode () ; 


Returns 


Current opmode. 


Description 


Function returns current operational mode of CAN module. 


Requires 


CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcon- 
troller must be connected to CAN transceiver (MCP2551 or similar) which is 
connected to CAN bus. 


Example 


if (CANGetOperationMode () == CAN MODE NORMAL) { . . . } ; 



CANInitialize 



Prototype 


void CANInitialize (char SJW, char BRP, char PHSEG1, char PHSEG2, 
char PROPSEG, char CAN CONFIG FLAGS); 


Returns 


Nothing. 


Description 


Initializes CAN. All pending transmissions are aborted. Sets all mask registers to to 
allow all messages. The Config mode is intemaly set by this function. Upon a execu- 
tion of this function Normal mode is set. Filter registers are set according to flag value: 

if (CAN CONFIG FLAGS & CAN CONFIG VALID XTD MSG != 0) 

// Set all filters to XTD MSG 
else if (config & CAN CONFIG VALID STD MSG != 0) 

// Set all filters to STD MSG 
else 

// Set half the filters to STD, and the rest to XTD MSG 

Parameters: 

■ sjw as defined in 18XXX8 datasheet (1-4) 

■ brp as defined in 18XXX8 datasheet (1-64) 

■ phsegi as defined in 18XXX8 datasheet (1-8) 

■ phseg2 as defined in 18XXX8 datasheet (1-8) 

■ propseg as defined in 18XXX8 datasheet (1-8) 

■ can config flags is formed from predefined constants (see CAN constants) 


Requires 


CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcon- 
troller must be connected to CAN transceiver (MCP2551 or similar) which is con- 
nected to CAN bus. 


Example 


CAN CONFIG PHSEG2 PRG ON S 
CAN CONFIG STD MSG & 
CAN CONFIG DBL BUFFER ON S 
CAN CONFIG VALID XTD MSG & 
CAN CONFIG LINE FILTER OFF; 

CANInitialize (1, 1, 3, 3, 1, init) ; // initialize CAN 



246 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 7 
Libraries 



CANSetBoudRate 



Prototype 


void CANSetBaudRate (char SJW, char BRP, char PHSEG1, char PHSEG2, 
char PROPSEG, char CAN CONFIG FLAGS); 


Returns 


Nothing. 


Description 


Sets CAN baud rate. Due to complexity of CAN protocol, you cannot simply force 
a bps value. Instead, use this function when CAN is in Config mode. Refer to 
datasheet for details. 

Parameters: 

■ sjw as defined in 18XXX8 datasheet (1-4) 

■ brp as defined in 18XXX8 datasheet (1-64) 

■ phsegi as defined in 18XXX8 datasheet (1-8) 

■ phseg2 as defined in 18XXX8 datasheet (1-8) 

■ propseg as defined in 18XXX8 datasheet (1-8) 

■ can config flags is formed from predefined constants (see CAN constants) 


Requires 


CAN must be in Config mode; otherwise the function will be ignored. 
CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcon- 
troller must be connected to CAN transceiver (MCP2551 or similar) which is con- 
nected to CAN bus. 


Example 


CAN CONFIG PHSEG2 PRG ON S 
CAN CONFIG STD MSG & 
CAN CONFIG DBL BUFFER ON S 
CAN CONFIG VALID XTD MSG & 
CAN CONFIG LINE FILTER OFF; 

CANSetBaudRate (1, 1, 3, 3, 1, init); 
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CANSetMask 



Prototype 


void CANSetFilter (char CAN FILTER, long value, char 
CAN CONFIG FLAGS); 


Returns 


Nothing. 


Description 


Function sets mask for advanced filtering of messages. Given value is bit adjust- 
ed to appropriate buffer mask registers. 

Parameters: 

■ can mask is one of predefined constant values (see CAN constants) 

■ value is the mask register value 

■ can config flags selects type of message to filter, either 

CAN CONFIG XTD MSG or CAN CONFIG STD MSG 


Requires 


CAN must be in Config mode; otherwise the function will be ignored. 

CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcontroller must 

be connected to CAN transceiver (MCP2551 or similar) which is connected to CAN bus. 


Example 


// Set all mask bits to 1, i.e. all filtered bits are relevant: 
CANSetMask( CAN MASK Bl, -1, CAN CONFIG XTD MSG) ; 

// Note that -1 is just a cheaper way to write OxFFFFFFFF. 
Complement will do the trick and fill it up with ones . 



CANSetFilter 



Prototype 


void CANSetFilter (char CAN FILTER, long value, char 
CAN CONFIG FLAGS); 


Returns 


Nothing. 


Description 


Function sets message filter. Given value is bit adjusted to appropriate buffer 
mask registers. 

Parameters: 

■ can filter is one of predefined constant values (see CAN constants) 

■ value is the filter register value 

■ can config flags selects type of message to filter, either 

CAN CONFIG XTD MSG or CAN CONFIG STD MSG 


Requires 


CAN must be in Config mode; otherwise the function will be ignored. 

CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcontroller must be 

connected to CAN transceiver (MCP2551 or similar) which is connected to CAN bus. 


Example 


// Set id of filter Bl Fl to 3: 

CANSetFilter ( CAN FILTER Bl Fl , 3, CAN CONFIG XTD MSG); 
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CANRead 



Prototype 


char CANRead (long *id, char *data, char *datalen, char 
*CAN RX MSG FLAGS); 


Returns 


Message from receive buffer or zero if no message found. 


Description 


Function reads message from receive buffer. If at least one full receive buffer is found, it is 
extracted and returned. If none found, function returns zero. Parameters: 

■ id is message identifier 

■ data is an array of bytes up to 8 bytes in length 

■ dataien is data length, from 1-8. 

■ can rx msg flags is value formed from constants (see CAN constants) 


Requires 


CAN must be in mode in which receiving is possible. 

CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcontroller must be 

connected to CAN transceiver (MCP2551 or similar) which is connected to CAN bus. 


Example 


char rev, rx, len, data[ 8] ; 
long id; 

// ... 

rx = ; 

// ... 

rev = CANRead(id, data, Len, rx) ; 



CANWrite 



Prototype 


unsigned short CANWrite (long id, char *data, char dataien, char 
CAN TX MSG FLAGS ) ; 


Returns 


Returns zero if message cannot be queued (buffer full). 


Description 


If at least one empty transmit buffer is found, function sends message on queue 

for transmission. If buffer is full, function returns 0. 

Parameters: 

■ id is CAN message identifier. Only 11 or 29 bits may be used depending on 
message type (standard or extended) 

■ data is array of bytes up to 8 bytes in length 

■ dataien is data length from 1-8 

■ can tx msg flags is value formed from constants (see CAN constants) 


Requires 


CAN must be in Normal mode. 

CAN routines are currently supported only by P18XXX8 PIC MCUs. Microcontroller must be 

connected to CAN transceiver (MCP2551 or similar) which is connected to CAN bus. 


Example 


char tx, data; 
long id; 

// ... 

tx = CAN TX PRIORITY & 

CAN TX XTD FRAME; 
// ... 
CANWrite (id, data, 2, tx) ; 
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CAN Constants 

There is a number of constants predefined in CAN library. To be able to use the 
library effectively, you need to be familiar with these. You might want to check the 
example at the end of the chapter. 

CAN_OP_MODE 

can op mode constants define CAN operation mode. Function 
CANSetOperationMode expects one of these as its argument: 



const char 

_CAN_MODE_BITS = OxEO, 

_CAN_MODE_NORMAL = 0x00, 

_CAN_MODE_SLEEP = 0x20, 

_CAN_MODE_LOOP = 0x4 0, 

_CAN_MODE_LISTEN = 0x60, 

CAN MODE CONFIG = 0x80; 



// Use this to access opmode bits 



CAN_CONFIG_FLAGS 

can config flags constants define flags related to CAN module configuration. 
Functions cANinitiaiize and CANSetBaudRate expect one of these (or a bitwise 
combination) as their argument: 



const char 










CAN CONFIG 


DEFAULT 


= OxFF, 


// 


11111111 


CAN CONFIG 


PHSEG2 PRG BIT 


= 0x01, 






CAN CONFIG 


PHSEG2 PRG ON 


= OxFF, 


// 


XXXXXXX1 


CAN CONFIG 


PHSEG2 PRG OFF 


= OxFE, 


// 


xxxxxxxo 


CAN CONFIG 


LINE FILTER BIT 


= 0x02, 






CAN CONFIG 


LINE FILTER ON 


= OxFF, 


// 


XXXXXX1X 


CAN CONFIG 


LINE FILTER OFF 


= OxFD, 


// 


XXXXXX0X 


CAN CONFIG 


SAMPLE BIT 


= 0x04, 






CAN CONFIG 


SAMPLE ONCE 


= OxFF, 


// 


XXXXX1XX 


CAN CONFIG 


SAMPLE THRICE 


= OxFB, 


// 


XXXXX0XX 


CAN CONFIG 


MSG TYPE BIT 


= 0x08, 






CAN CONFIG 


STD MSG 


= OxFF, 


// 


XXXX1XXX 


CAN CONFIG 


XTD MSG 


= 0xF7, 


// 


XXXX0XXX 


CAN CONFIG 


DBL BUFFER BIT 


= 0x10, 






CAN CONFIG 


DBL BUFFER ON 


= OxFF, 


// 


XXX1XXXX 


CAN CONFIG 


DBL BUFFER OFF 


= OxEF, 


// 


XXX0XXXX 
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0x60, 








OxFF, 


// 


X11XXXXX 




OxDF, 


// 


X10XXXXX 




OxBF, 


// 


X01XXXXX 




0x9F; 


// 


xooxxxxx 





_CAN_CONFIG_MSG_BITS 

_CAN_CONFIG_ALL_MSG 
_CAN_CONFIG_VALID_XTD_MSG 
_CAN_CONFIG_VALID_STD_MSG 
CAN CONFIG ALL VALID MSG 



You may use bitwise AND (&) to form config byte out of these values. For example: 



init = _CAN_CONFIG_SAMPLE_THRICE & 
_CAN_CONFIG_PHSEG2_PRG_ON & 
_CAN_CONFIG_STD_MSG S 
_CAN_CONFIG_DBL_BUFFER_ON & 
_CAN_CONFIG_VALID_XTD_MSG & 
CAN CONFIG LINE FILTER OFF; 



CANInitialize (1, 1, 3, 3, 1, init); 



// initialize CAN 



CAN TX MSG FLAGS 



can tx msg flags are flags related to transmission of a CAN message: 

const char 



CAN 


TX 


PRIORITY BITS 


= 0x03, 






CAN 


TX 


PRIORITY 


= OxFC, 


// 


xxxxxxoo 


CAN 


TX 


PRIORITY 1 


= OxFD, 


// 


XXXXXX01 


CAN 


TX 


PRIORITY 2 


= OxFE, 


// 


XXXXXX10 


CAN 


TX 


PRIORITY 3 


= OxFF, 


// 


XXXXXX11 


CAN 


TX 


FRAME BIT 


= 0x08, 






CAN 


TX 


STD FRAME 


= OxFF, 


// 


XXXXX1XX 


CAN 


TX 


XTD FRAME 


= 0xF7, 


// 


xxxxxoxx 


CAN 


TX 


RTR BIT 


= 0x40, 






CAN 


TX 


NO RTR FRAME 


= OxFF, 


// 


X1XXXXXX 


CAN 


TX 


RTR FRAME 


= OxBF; 


// 


xoxxxxxx 



You may use bitwise AND (&) to adjust the appropriate flags. For example: 

// form value to be used with CANSendMessage : 
send_config = _CAN_TX_PRIORITY_0 & 

_CAN_TX_XTD_FRAME & 

_CAN_TX_NO_RTR_FRAME ; 

CANSendMessage (id, data, 1, send_config) ; 
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CAN_RX_MSG_FLAGS 

can rxmsg flags are flags related to reception of CAN message. If a particular bit is set; cor- 
responding meaning is TRUE or else it will be FALSE. 



const char 






CAN RX FILTER BITS 


= 0x07, 


// 


CAN RX FILTER 1 


= 0x00, 




CAN RX FILTER 2 


= 0x01, 




CAN RX FILTER 3 


= 0x02, 




CAN RX FILTER 4 


= 0x03, 




CAN RX FILTER 5 


= 0x04, 




CAN RX FILTER 6 


= 0x05, 




CAN RX OVERFLOW 


= 0x08, 


// 


CAN RX INVALID MSG 


= 0x10, 


// 


CAN RX XTD FRAME 


= 0x20, 


// 


CAN RX RTR FRAME 


= 0x40, 


// 


CAN RX DBL BUFFERED 


= 0x80; 


// 



Use this to access filter bits 



Set if Overflowed else cleared 
Set if invalid else cleared 
Set if XTD message else cleared 
Set if RTR message else cleared 
// Set if this message was hard 
ware double-buffered 



You may use bitwise AND ( ) to adjust the appropriate flags. For example: 

if (MsgFlag S _CAN_RX_0VERFL0W != 0) { 

// Receiver overflow has occurred. 
// We have lost our previous message. 



CAN_MASK 

can mask constants define mask codes. Function CANSetMask expects one of 
these as its argument: 

#const char 

_CAN_MASK_B1 = 0, 

_CAN_MASK_B2 = 1 ; 

CAN FILTER 
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can filter constants define filter codes. Function cANSetFiiter expects one of these as its 
argument: 

const char 

_CAN_FILTER_B1_F1 = 0, 

_CAN_FILTER_B1_F2 = 1, 

_CAN_FILTER_B2_F1 = 2, 

_CAN_FILTER_B2_F2 = 3, 
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_CAN_FILTER_B2_F3 = 4, 
_CAN_FILTER_B2_F4 = 5; 

Library Example 

This is a simple demonstration of CAN Library routines usage. First node initiates 
the communication with the second node by sending some data to its address. The 
second node responds by sending back the data incremented by 1 . First node then 
does the same and sends incremented data back to second node, etc. 
Code for the first CAN node: 

unsigned char Can Init Flags, Can_Send_Flags, Can Rev Flags; // can flags 
unsigned char Rx_Data_Len; // received data length in bytes 

char RxTx_Data[ 8] ; // can rx/tx data buffer 

char Msg_Rcvd; // reception flag 

const long lD_lst = 12111, ID_2nd = 3; // node IDs 
long Rx_ID; 

void main ( ) { 

PORTC =0; // clear PORTC 

TRISC =0; // set PORTC as output 



Can Init Flags = 
Can_Send_Flags = 
Can_Rcv Flags = 



// 

// clear flags 

// 



Can_Send_Flags = _CAN_TX_PRIORITY_0 & // form value to be used 
_CAN_TX_XTD_FRAME & // with CANWrite 
_CAN_TX_NO_RTR_FRAME ; 

Can_Init_Flags = _CAN_CONFIG_SAMPLE_THRICE & // form value to be used 
_CAN_CONFIG_PHSEG2_PRG_ON & // with CANInit 
_CAN_CONFIG_XTD_MSG & 
_CAN_CONFIG_DBL_BUFFER_ON & 
_CAN_CONFIG_VALID_XTD_MSG; 

CANInitialize(l,3,3,3,l,Can_Init_Flags) ; // Initialize CAN module 
CANSetOperationMode (_CAN_MODE_CONFIG, OxFF) ; // set CONFIGURATION mode 
CANSetMask(_CAN_MASK_Bl,-l,_CAN_CONFIG_XTD_MSG) ; // set all maskl bits to 

ones 
CANSetMask(_CAN_MASK_B2,-l,_CAN_CONFIG_XTD_MSG) ; // set all mask2 bits to 

ones 
CANSetFilter (_CAN_FILTER_B2_F4, ID_2nd,_CAN_CONFIG_XTD_MSG) ;// set id of 

filter B2_F4 to 2nd node ID 

CANSetOperationMode (_CAN_MODE_NORMAL, OxFF) ; // set NORMAL mode 

RxTx_Data[ 0] = 9; // set initial data to be sent 
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CANWrite (ID_lst, RxTx_Data, 1, Can_Send_Flags) ; // send initial message 

while (1) { // endless loop 

Msg_Rcvd = CANRead(&Rx_ID , RxTx_Data , &Rx_Data_Len, &Can_Rcv_Flags) ; // 
receive message 

if ( (Rx ID = ID 2nd) && Msg_Rcvd) { // if message received check id 
PORTC = RxTx_Data[ 0] ; // id correct, output data at PORTC 
RxTx Data[ 0] ++; // increment received data 
Delayjns (10) ; 
CANWrite (ID_lst, RxTx_Data, 1, Can_Send_Flags) ; // send incremented data back 



Code for the second CAN node: 

unsigned char Can_Init_Flags, Can_Send_Flags , Can_Rcv_Flags ; // can 

flags 

unsigned char Rx Data Len; // received data length in bytes 

char RxTx_Data[ 8] ; // can rx/tx data buffer 

char Msg Rcvd; // reception flag 

const long lD_lst = 12111, ID_2nd = 3; // node IDs 

long Rx_ID; 

void main ( ) { 



PORTC = 0; 




TRISC = 0; 




Can Init Flags = 


= 


Can Send Flags = 


= 


Can Rev Flags 


= 



// clear PORTC 

// set PORTC as output 

// 

// clear flags 

// 



Can Send_Flags 



_CAN_TX_PRIORITY_0 & // form value to be used 
_CAN_TX_XTD_FRAME & // with CANWrite 
CAN TX NO RTR FRAME; 



Can Init Flags 



_CAN_C0NFIGJ3AMPLE_THRICE & // form value to be used 
_CAN_C0NFIG_PHSEG2_PRG_0N S // with CANInit 
_CAN_C0NFIG_XTD_MSG & 
_CAN_CONFIG_DBL_BUFFER_ON & 
_CAN_CONFIG_VALID_XTD_MSG & 
CAN CONFIG LINE FILTER OFF; 



CANInitialize (1, 3, 3, 3, l,Can Init Flags); // initialize external CAN module 
CANSetOperationMode (_CAN_MODE_CONFIG, OxFF) ; // set CONFIGURATION mode 
CANSetMask(_CAN_MASK_Bl,-l,_CAN_CONFIG_XTD_MSG) ; // set all maskl 
bits to ones 
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CANSetMask(_CAN_MASK_B2,-l,_CAN_CONFIG_XTD_MSG) ; // set all mask2 
bits to ones 

CANSetFilter (_CAN_FILTER_B2_F3, ID_lst , _CAN_CONFIG_XTD_MSG) ; // set 
id of filter B2_F3 to 1st node ID 

CANSetOperationMode (_CAN_MODE_NORMAL, OxFF) ; // set NORMAL mode 

while (1) { // endless loop 

Msg_Rcvd = CANRead (&Rx_ID , RxTx_Data , &Rx_Data_Len, 
&Can_Rcv_Flags ) ; // receive message 

if ( (Rx ID = ID 1st) && Msg_Rcvd) { // if message received check id 
PORTC = RxTx_Data[ 0] ; // id correct, output data at PORTC 
RxTx_Data[ 0] ++; // increment received data 
CANWrite (ID_2nd, RxTx_Data, 1, Can_Send_Flags) ; // send incre- 
mented data back 



HW Connection 



vcc^ 



*■ CANRXofMCU 



■*■ CANTXofMCU 
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Example of interfacing CAN transceiver with MCU and bus 
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CANSPI LIBRARY 

The SPI module is available with a number of the PIC compliant MCUs. The mikroC 
PRO for PIC provides a library (driver) for working with mikroElektronika's CANSPI 
Add-on boards (with MCP2515 or MCP2510) via SPI interface. 
The CAN is a very robust protocol that has error detection and signalization, 
self-checking and fault confinement. Faulty CAN data and remote frames are re- 
transmitted automatically, similar to the Ethernet. 

Data transfer rates depend on distance. For example, 1 Mbit/s can be achieved at net- 
work lengths below 40m while 250 Kbit/s can be achieved at network lengths below 
250m. The greater distance the lower maximum bitrate that can be achieved. The lowest 
bitrate defined by the standard is 200Kbit/s. Cables used are shielded twisted pairs. 

CAN supports two message formats: 

■ Standard format, with 11 identifier bits; and 

■ Extended format, with 29 identifier bits. 

Note: 

■ Consult the CAN standard about CAN bus termination resistance. 

■ An effective CANSPI communication speed depends on SPI and certainly is 
slower than "real" CAN. 

■ The library uses the SPI module for communication. User must initialize SPI 
module before using the SPI Graphic Led Library. 

For MCUs with two SPI modules it is possible to initialize both of them and then 
switch by using the spiSetActive ( ) routine. 

■ CANSPI module refers to mikroElektronika's CANSPI Add-on board connected 
to SPI module of MCU. 



External dependecies of CANSPI Library 



The following variables 

must be defined in all 

projects using CANSPI 

Library: 


Description: 


Example: 


extern sfr sbit 

CanSpi CS; 


Chip Select line. 


RCO bit; 


extern sfr sbit 

CanSpi Rst; 


Reset line. 


sbit CanSpi Rst at 
RC2 bit; 


extern sfr sbit 

CanSpi CS Direction; 


Direction of the Chip 
Select pin. 


sbit CanSpi CS Direction 
at TRISCO bit; 


extern sfr sbit 

CanSpi Rst Direction; 


Direction of the Reset pin. 


sbit CanSpi Rst Direction 
at TRISC2 bit; 
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Library Routines 

- CANSPISetOperationMode 

- CANSPIGetOperationMode 

- CANSPIInitialize 

- CANSPISetBaudRate 

- CANSPISetMask 

- CANSPISetFilter 

- CANSPIread 

- CANSPIWrite 

The following routines are for an internal use by the library only: 

- RegsToCANSPIID 

- CANSPIIDToRegs 

Be sure to check CANSPI constants necessary for using some of the functions. 
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CANSPISetOperationMode 



Prototype 


void CANSPISetOperationMode (char mode, char WAIT) ; 


Returns 


Nothing. 


Description 


Sets the CANSPI module to requested mode. 

Parameters: 

- mode: CANSPI module operation mode. Valid values: canspi op mode con- 
stants (see CANSPI constants). 

-wait: CANSPI mode switching verification request. If wait = = o, the call is non- 
blocking. The function does not verify if the CANSPI module is switched to 
requested mode or not. Caller must use cANSPiGetOperationMode to verify cor- 
rect operation mode before performing mode specific operation. If wait != o, the 
call is blocking - the function won't "return" until the requested mode is set. 


Requires 


The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 

similar hardware. See connection example at the bottom of this page. 


Example 


// set the CANSPI module into configuration mode (wait inside 
CANSPISetOperationMode until this mode is set) 
CANSPISetOperationMode ( CANSPI MODE CONFIG, OxFF) ; 



CANSPiGetOperationMode 



Prototype 


char CANSPiGetOperationMode ( ) ; 


Returns 


Current operation mode. 


Description 


The function returns current operation mode of the CANSPI module. Check can- 
spi op mode constants (see CANSPI constants) or device datasheet for opera- 
tion mode codes. 


Requires 


The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 

similar hardware. See connection example at the bottom of this page. 


Example 


// check whether the CANSPI module is in Normal mode and if it 

is do something. 

if (CANSPiGetOperationMode () == CANSPI MODE NORMAL) { 

} 
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CANSPIInitialize 



Prototype 


void CANSPIInitialize ( char SJW, char BRP, char PHSEG1, char 

PHSEG2, char PROPSEG, char CANSPI CONFIG FLAGS); 


Returns 


Nothing. 


Description 


Initializes the CANSPI module. 

Stand-Alone CAN controller in the CANSPI module is set to: 

- Disable CAN capture 

- Continue CAN operation in Idle mode 

- Do not abort pending transmissions 

- Fcan clock: 4*Tcy (Fosc) 

- Baud rate is set according to given parameters 

- CAN mode: Normal 

- Filter and mask registers IDs are set to zero 

- Filter and mask message frame type is set according to can config flags value 

Sam, seg2phts, wAKFiL and dben bits are set according to canspi config flags value. 
Parameters: 

- sjw as defined in CAN controller's datasheet 

- brp as defined in CAN controller's datasheet 

- phsegi as defined in CAN controller's datasheet 

- phseg2 as defined in CAN controller's datasheet 

- propseg as defined in CAN controller's datasheet 

- can config flags is formed from predefined constants (see CANSPI con- 
stants) 


Requires 


Global variables: 

- CanSpi cs : Chip Select line 

- CanSpi Rst: Reset line 

- CanSpi cs Direction: Direction of the Chip Select pin 

- CanSpi Rst Direction: Direction of the Reset pin 
must be defined before using this function. 

The CANSPI routines are supported only by MCUs with the SPI module. 
The SPI module needs to be initialized. See the SPMJnit and 
SPI1_lnit_Advanced routines. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or sim- 
ilar hardware. See connection example at the bottom of this page. 
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// CANSPI module connections 






sbit CanSpi CS at RCO bit; 






sbit CanSpi CS Direction at TRISCO bit; 






sbit CanSpi Rst at RC2 bit; 






sbit CanSpi Rst Direction at TRISC2 bit; 






// End CANSPI module connections 






// initialize the CANSPI module with the appropriate 


baud rate 




and message acceptance flags along with the sampling 


rules 




char CanSPi Init Flags; 




Example 


CanSPi Init Flags = CANSPI CONFIG SAMPLE THRICE & 
value to be used 


// form 




CANSPI CONFIG PHSEG2 PRG ON S 


// with 




CANSPIInitialize 






CANSPI CONFIG XTD MSG S 






CANSPI CONFIG DBL BUFFER ON & 






CANSPI CONFIG VALID XTD MSG; 






SPI1 Init(); // initialize SPI module 






CANSPIInitialize (1, 3, 3, 3, 1, CanSpi Init Flags); // 


initialize 




external CANSPI module 
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CANSPISetBaudRate 



Prototype 


void CANSPISetBaudRate ( char SJW, char BRP, char PHSEG1, char 

PHSEG2, char PROPSEG, char CANSPI CONFIG FLAGS); 


Returns 


Nothing. 


Description 


Sets the CANSPI module baud rate. Due to complexity of the CAN protocol, 
you can not simply force a bps value. Instead, use this function when the 
CANSPI module is in Config mode. 

sam, seg2phts and wakfil bits are set according to canspi config flags 
value. Refer to datasheet for details. 

Parameters: 

- sjw as defined in CAN controller's datasheet 

- brp as defined in CAN controller's datasheet 

- phsegi as defined in CAN controller's datasheet 

- phseg2 as defined in CAN controller's datasheet 

- propseg as defined in CAN controller's datasheet 

- can config flags is formed from predefined constants (see CANSPI constants) 


Requires 


The CANSPI module must be in Config mode, otherwise the function will be 
ignored. See CANSPISetOperationMode. 

The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 
similar hardware. See connection example at the bottom of this page. 


Example 


// set required baud rate and sampling rules 
char canspi config flags; 

CANSPISetOperationMode (CANSPI MODE CONFIG, OxFF) ; // set CONFIGU- 
RATION mode (CANSPI module mast be in config mode for baud rate 
settings ) 

canspi config flags = CANSPI CONFIG SAMPLE THRICE & 

CANSPI CONFIG PHSEG2 PRG ON & 
CANSPI CONFIG STD MSG & 
CANSPI CONFIG DBL BUFFER ON & 
CANSPI CONFIG VALID XTD MSG & 
CANSPI CONFIG LINE FILTER OFF; 
CANSPISetBaudRate (1, 1, 3, 3, 1, canspi config flags); 
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CANSPISetMask 



Prototype 


void CANSPISetMask (char CANSPI MASK, long val, char CANSPI CON- 
FIG FLAGS) ; 


Returns 


Nothing. 


Description 


Configures mask for advanced filtering of messages. The parameter value is 
bit-adjusted to the appropriate mask registers. 

Parameters: 

- can mask: CANSPI module mask number. Valid values: canspi mask costants 
(see CANSPI constants) 

- vai: mask register value 

- can config flags: selects type of message to filter. Valid values: 

CANSPI CONFIG ALL VALID MSG, 

CANSPI CONFIG MATCH MSG TYPE and CANSPI CONFIG STD MSG, 

CANSPI CONFIG MATCH MSG TYPE and CANSPI CONFIG XTD MSG. 

(see CANSPI constants) 


Requires 


The CANSPI module must be in Config mode, otherwise the function will be 
ignored. See CANSPISetOperationMode. 

The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 
similar hardware. See connection example at the bottom of this page. 


Example 


// set the appropriate filter mask and message type value 
CANSPISetOperationMode ( CANSPI MODE CONFIG, OxFF) ; 

// set CONFIGURATION mode (CANSPI module must be in config mode 
for mask settings) 

// Set all Bl mask bits to 1 (all filtered bits are relevant) : 
// Note that -1 is just a cheaper way to write OxFFFFFFFF. 
// Complement will do the trick and fill it up with ones. 
CANSPISetMask ( CANSPI MASK Bl, -1, CANSPI CONFIG MATCH MSG TYPE 
& CANSPI CONFIG XTD MSG) ; 
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CANSPISetFilter 



Prototype 


void CANSPISetFilter (char CANSPI FILTER, long val, char 
CANSPI CONFIG FLAGS) ; 


Returns 


Nothing. 


Description 


Configures message filter. The parameter value is bit-adjusted to the appropri- 
ate filter registers. 

Parameters: 

- can filter: CANSPI module filter number. Valid values: canspi filter 
constants (see CANSPI constants) 

- vai: filter register value 

- can config flags: selects type of message to filter. Valid values: 

CANSPI CONFIG ALL VALID MSG, 

CANSPI CONFIG MATCH MSG TYPE and CANSPI CONFIG STD MSG, 

CANSPI CONFIG MATCH MSG TYPE and CANSPI CONFIG XTD MSG. 

(see CANSPI constants) 


Requires 


The CANSPI module must be in Config mode, otherwise the function will be 
ignored. See CANSPISetOperationMode. 

The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 
similar hardware. See connection example at the bottom of this page. 


Example 


// set the appropriate filter value and message type 
CANSPISetOperationMode ( CANSPI MODE CONFIG, OxFF) ; 

// set CONFIGURATION mode (CANSPI module must be in config mode 
for filter settings) 

/* Set id of filter Bl Fl to 3: */ 

CANSPISetFilter ( CANSPI FILTER Bl Fl, 3, CANSPI CONFIG XTD MSG); 
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CANSPIRead 



Prototype 


char CANSPIRead (long * id, char * rd data, char *data len, char 
* CANSPI RX MSG FLAGS); 


Returns 


- o if nothing is received 

- Oxff if one of the Receive Buffers is full (message received) 


Description 


If at least one full Receive Buffer is found, it will be processed in the following 
way: 

- Message ID is retrieved and stored to location provided by the id parameter 

- Message data is retrieved and stored to a buffer provided by the rd data parameter 

- Message length is retrieved and stored to location provided by the 
data len parameter 

- Message flags are retrieved and stored to location provided by the 
can rx msg flags parameter 

Parameters: 

- id: message identifier storage address 

- rd data : data buffer (an array of bytes up to 8 bytes in length) 

- data len: data length storage address. 

- can rx msg flags : message flags storage address 


Requires 


The CANSPI module must be in a mode in which receiving is possible. See 
CANSPISetOperationMode. 

The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 
similar hardware. See connection example at the bottom of this page. 


Example 


// check the CANSPI module for received messages. If any was 

received do something. 

char msg rcvd, rx flags, data len; 

char data[ 8] ; 

long msg id; 

CANSPISetOperationMode (CA NSPI MODE NORMAL, OxFF) ; 

// set NORMAL mode (CANSPI module must be in mode in which 

receive is possible) 

rx flags = 0; 

// clear message flags 

if (msg rcvd = CANSPIRead (msg id, data, data len, rx flags)) { 

} 
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CANSPIWrite 



Prototype 


char CANSPIWrite (long id, char *wr data, char data len, char CAN- 
SPI TX MSG FLAGS) ; 


Returns 


- o if all Transmit Buffers are busy 

- Oxff if at least one Transmit Buffer is available 


Description 


If at least one empty Transmit Buffer is found, the function sends message in 
the queue for transmission. 

Parameters: 

- id: CAN message identifier. Valid values: 11 or 29 bit values, depending on 
message type (standard or extended) 

- wr data : data to be sent (an array of bytes up to 8 bytes in length) 

- data len: data length. Valid values: 1 to 8 

- can rx msg flags: message flags 


Requires 


The CANSPI module must be in mode in which transmission is possible. See 
CANSPISetOperationMode. 

The CANSPI routines are supported only by MCUs with the SPI module. 

MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or 
similar hardware. See connection example at the bottom of this page. 


Example 


// send message extended CAN message with the appropriate ID and 

data 

char tx flags; 

char data[ 8] ; 

long msg id; 

CANSPISetOperationMode ( CANSPI MODE NORMAL, OxFF) ; 

// set NORMAL mode (CANSPI must be in mode in which transmission 

is possible) 

tx flags = CANSPI TX PRIORITY S CANSPI TX XTD FRAME; 

// set message flags 

CANSPIWrite (msg id, data, 2, tx flags); 
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CANSPI Constants 

There is a number of constants predefined in the CANSPI library. You need to be 
familiar with them in order to be able to use the library effectively. Check the exam- 
ple at the end of the chapter. 

CANSPI OP MODE 



The canspi op mode constants define CANSPI operation mode. Function 
CANSPISetOperationMode expects one of these as it's argument: 



const char 

_CANSPI_MODE_BITS = OxEO, 

_CANSPI_MODE_NORMAL = 0x0 0, 

_CANSPI_MODE_SLEEP = 0x20, 

_CANSPI_MODE_LOOP = 0x40, 

_CANSPI_MODE_LISTEN = 0x60, 

CANSPI MODE CONFIG = 0x8 0; 



// Use this to access opmode bits 



CANSPI CONFIG FLAGS 



The canspi config flags constants define flags related to the CANSPI module 
configuration. The functions CANSPIInitialize, CANSPISetBaudRate, 
CANSPISetMask and CANSPISetFilter expect one of these (or a bitwise combina- 
tion) as their argument: 



const char 

_CANSPI_CONFIG_DEFAULT 

_CANSPI_CONFIG_PHSEG2_PRG_BIT 

_CANSPI_CONFIG_PHSEG2_PRG_ON 

_CANSPI_CONFIG_PHSEG2_PRG_OFF 

_CANSPI_CONFIG_LINE_FILTER_BIT 

_CANSPI_CONFIG_LINE_FILTER_ON 

_CANSPI_CONFIG_LINE_FILTER_OFF 

_CANSPI_CONFIG_SAMPLE_BIT 
_CANSPI_CONFIG_SAMPLE_ONCE 
CANSPI CONFIG SAMPLE THRICE 



_CANSPI_CONFIG_MSG_TYPE_ 
_CANSPI_CONFIG_STD_MSG 
CANSPI CONFIG XTD MSG 



3IT 



OxFF, 


// 


11111111 


0x01, 






OxFF, 


// 


XXXXXXX1 


OxFE, 


// 


xxxxxxxo 


0x02, 






OxFF, 


// 


XXXXXX1X 


OxFD, 


// 


xxxxxxox 


0x04, 






OxFF, 


// 


XXXXX1XX 


OxFB, 


// 


xxxxxoxx 


0x08, 






OxFF, 


// 


XXXX1XXX 


0xF7, 


// 


xxxxoxxx 
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_CANSPI_CONFIG_DBL_BUFFER_BIT 

_CANSPI_CONFIG_DBL_BUFFER_ON 
_CANSPI_CONFIG_DBL_BUFFER_OFF 

_CANSPI_CONFIG_MSG_BITS 
_CANSPI_CONFIG_ALL_MSG 
_CANSPI_CONFIG_VALID_XTD_MSG 
_CANSPI_CONFIG_VALID_STD_MSG 
CANSPI CONFIG ALL VALID MSG 



0x10, 






OxFF, 


// 


XXX1XXXX 


OxEF, 


// 


xxxoxxxx 


0x60, 






OxFF, 


// 


X11XXXXX 


OxDF, 


// 


X10XXXXX 


OxBF, 


// 


X01XXXXX 


0x9F; 


// 


xooxxxxx 



You may use bitwise AND (&) to form config byte out of these values. For example: 



init = _CANSPI_CONFIG_SAMPLE_THRICE & 
_CANSPI_CONFIG_PHSEG2_PRG_ON S 
_CANSPI_CONFIG_STD_MSG & 
_CANSPI_CONFIG_DBL_BUFFER_ON & 
_CANSPI_CONFIG_VALID_XTD_MSG & 
_CANSPI_CONFIG_LINE_FILTER_OFF; 

CANSPIInitialize (1, 1, 3, 3, 1, init); 

CANSPI TX MSG FLAGS 



// initialize CANSPI 



canspi tx msg flags are flags related to transmission of a CAN message: 



const char 

_CANSPI_TX_PRIORITY_BITS 

_CANSPI_TX_PRIORITY_0 

_CANSPI_TX_PRIORITY_l 

_CANSPI_TX_PRIORITY_2 

_CANSPI_TX_PRIORITY_3 

_CANSPI_TX_FRAME_BIT 
_CANSPI_TX_STD_FRAME 
_CANSPI_TX_XTD_FRAME 

_CANSPI_TX_RTR_BIT 
_CANSPI_TX_NO_RTR_FRAME = 
CANSPI TX RTR FRAME 



0x03, 






■ OxFC, 


// 


xxxxxxoo 


■ OxFD, 


// 


XXXXXX01 


■ OxFE, 


// 


XXXXXX10 


■ OxFF, 


// 


XXXXXX11 


0x08, 






OxFF, 


// 


XXXXX1XX 


0xF7, 


// 


xxxxxoxx 


0x40, 






OxFF, 


// 


X1XXXXXX 


OxBF; 


// 


xoxxxxxx 



You may use bitwise AND ( ) to adjust the appropriate flags. For example: 

/* form value to be used as sending message flag : */ 
send_config = _CANSPI_TX_PRIORITY_0 & 

_CANSPI_TX_XTD_FRAME & 

_CANSPI_TX_NO_RTR_FRAME; 

CANSPIWrite (id, data, 1, send_conf ig) ; 
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CANSPI_RX_MSG_FLAGS 

canspirxmsg flags are flags related to reception of CAN message. If a particu- 
lar bit is set then corresponding meaning is TRUE or else it will be FALSE. 



const char 

_CANSPI_RX_FILTER_BITS = 
_CANSPI_RX_FILTER_1 
_CANSPI_RX_FILTER_2 
_CANSPI_RX_FILTER_3 
_CANSPI_RX_FILTER_4 
_CANSPI_RX_FILTER_5 
_CANSPI_RX_FILTER_6 

_CANSPI_RX_OVERFLOW 
_CANSPI_RX_INVALID_MSG = 
_CANSPI_RX_XTD_FRAME 

cleared 
_CANSPI_RX_RTR_FRAME 

cleared 
_CANSPI_RX_DBL_BUFFERED 

ware double-buffered 



0x07, // Use this to access filter bits 

0x00, 

0x01, 

0x02, 

0x03, 

0x04, 

0x05, 



0x08, // Set if Overflowed else cleared 
0x10, // Set if invalid else cleared 
0x20, // Set if XTD message else 

= 0x40, // Set if RTR message else 

= 0x80; // Set if this message was hard 



You may use bitwise AND (&) to adjust the appropriate flags. For example: 

if (MsgFlag S _CANSPI_RX_OVERFLOW != 0) { 

// Receiver overflow has occurred. 
// We have lost our previous message. 
} 

CANSPI_MASK 

The cans pi mask constants define mask codes. Function CANSPISetMask expects 
one of these as it's argument: 

const char 

_CANSPI_MASK_B1 = 0, 
_CANSPI_MASK_B2 = 1 ; 

CANSPI FILTER 



The canspi filter constants define filter codes, 
expects one of these as it's argument: 

const char 

_CANSPI_FILTER_B1_F1 = 0, 

_CANSPI_FILTER_B1_F2 = 1, 

_CANSPI_FILTER_B2_F1 = 2, 

CANSPI FILTER B2 F2 = 3, 



Functions CANSPISetFilter 
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_CANSPI_FILTER_B2_F3 

CANSPI FILTER B2 F4 



Library Example 

This is a simple demonstration of CANSPI Library routines usage. First node initi- 
ates the communication with the second node by sending some data to its address. 
The second node responds by sending back the data incremented by 1. First node 
then does the same and sends incremented data back to second node, etc. 

Code for the first CANSPI node: 

unsigned char Can_Init_Flags, Can_Send_Flags, Can_Rcv_Flags ; // can 

flags 

unsigned char Rx Data Len; // received data length in bytes 

char RxTx_Data[ 8] ; // can rx/tx data buffer 

char Msg Rcvd; // reception flag 

const long lD_lst = 12111, ID_2nd = 3; // node IDs 

long Rx_ID; 

// CANSPI module connections 
sbit CanSpi_CS at RCOJoit; 

sbit CanSpi_CS_Direction at TRISCOJoit; 
sbit CanSpi_Rst at RC2_bit; 

sbit CanSpi_Rst_Direction at TRISC2_bit; 
// End CANSPI module connections 

void main ( ) { 



ANSEL = 0; 




ANSELH = 0; 




PORTB = 0; 




TRISB = 0; 




Can Init Flags = 


= 


Can Send Flags = 


= 


Can Rev Flags 


= 



// Configure AN pins as digital I/O 



// clear PORTB 

// set PORTB as output 

// 



// clear flags 
// 



Can Send_Flags 



_CANSPI_TX_PRIORITY_0 S // form value to be used 
_CANSPI_TX_XTD_FRAME & // with CANSPIWrite 
CANSPI TX NO RTR FRAME; 



Can_Init_Flags = _CANSPI_CONFIG_SAMPLE_THRICE & // Form value to be used 
_CANSPI_CONFIG_PHSEG2_PRG_ON & // with CANSPIInit 
_CANSPI_CONFIG_XTD_MSG & 
_CANSPI_CONFIG_DBL_BUFFER_ON S 
CANSPI CONFIG VALID XTD MSG; 
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SPIl Init () ; 



// initialize SPIl module 



CANSPIInitialize(l,3,3,3,l,Can_Init_Flags) ; // Initialize external CANSPI 
module 

CANSPISetOperationMode (_CANSPI_M0DE_CONFIG, OxFF) ; // set CONFIGURATION mode 
CANSPISetMask(_CANSPI_MASK_Bl,-l,_CANSPI_CONFIG_XTD_MSG) ; // set 
all maskl bits to ones 

CANSPISetMask(_CANSPI_MASK_B2,-l,_CANSPI_CONFIG_XTD_MSG) ; // set 
all mask2 bits to ones 

CANSPISetFilter (_CANSPI_FILTER_B2_F4 , ID_2nd, _CANSPI_CONFIG_XTD_MSG) ; 
// set id of filter B2_F4 to 2nd node ID 

CANSPISetOperationMode (_CANSPI_MDDE_NOPMAL, OxFF) ; // set NORMAL mode 

RxTx_Data[ 0] = 9; // set initial data to be sent 

CANSPIWrite (ID_lst, RxTx_Data, 1, Can_Send_Flags) ; // send initial 
message 

while (1) { // endless loop 

Msg_Rcvd = CANSPIRead (SRx_ID , RxTx_Data , &Rx_Data_Len, 
SCan Rev Flags);// receive message 

if ( (Rx_ID == ID_2nd) && Msg_Rcvd) { 
// if message received check id 

PORTB = RxTx_Data[ 0] ; 
// id correct, output data at PORTC 

RxTx_Data[ 0] + + ; 
// increment received data 
Delay_ms (10) ; 

CANSPIWrite (ID_lst, RxTx_Data, 1, Can_Send_Flags) ; 
// send incremented data back 
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Code for the second CANSPI node: 

unsigned char Can_Init_Flags, Can_Send_Flags , Can_Rcv_Flags ; // can 

flags 

unsigned char Rx Data Len; // received data length in bytes 

char RxTx_Data[ 8] ; // can rx/tx data buffer 

char Msg Rcvd; // reception flag 

const long lD_lst = 12111, ID_2nd = 3; // node IDs 

long Rx_ID; 

// CANSPI module connections 
sbit CanSpi_CS at RC0_bit; 

sbit CanSpi_CS_Direction at TRISCOJoit; 
sbit CanSpi_Rst at RC2_bit; 

sbit CanSpi_Rst_Direction at TRISC2_bit; 
// End CANSPI module connections 

void main ( ) { 

// Configure AN pins as digital I/O 



ANSEL 


= 0; 


ANSELH 


= 0; 


PORTB = 


0; 


TRISB = 


0; 



Can_Init_Flags = 
Can Send Flags = 
Can Rev Flags = 



// clear PORTB 

// set PORTB as output 

// 

// clear flags 

// 



Can_Send_Flags = _CANSPI_TX_PRIORITY_0 & // form value to be used 
_CANSPI_TX_XTD_FRAME & // with CANSPIWrite 
_CANSPI_TX_NO_RTR_FRAME; 

Can_Init_Flags = _CANSPI_CONFIG_SAMPLE_THRICE & // Form value to be used 
_CANSPI_CONFIG_PHSEG2_PRG_ON S // with CANSPIInit 
_CANSPI_CONFIG_XTD_MSG & 
_CANSPI_CONFIG_DBL_BUFFER_ON & 
_CANSPI_CONFIG_VALID_XTD_MSG & 
_CANSPI_CONFIG_LINE_FILTER_OFF; 

SPIl_Init () ; // initialize SPI1 module 

CANSPIInitialize ( 1, 3, 3, 3, 1, Can Init Flags); // initialize external 
CANSPI module 

CANSPISetOperationMode (_CANSPI_MODE_CONFIG, OxFF) ; // set CONFIGU- 
RATION mode 

CANSPISetMask (_CANSPI_MASK_B1, -1, _CANSPI_CONFIG_XTD_MSG) ; // set 
all maskl bits to ones 

CANSPISetMask (_CANSPI_MASK_B2, -1,_CANSPI_C0NFIG_XTD_MSG) ; // set 
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all mask2 bits to ones 

CANSPISetFilter (_CANSPI_FILTER_B2_F3, ID_lst , _CANSPI_CONFIG_XTD_MSG) ; 
// set id of filter B2_F3 to 1st node ID 

CANSPISetOperationMode(_CANSPI_MODE_NORMAL, OxFF) ;// set NORMAL mode 

while (1) { // endless loop 

Msg_Rcvd = CANSPIRead (&Rx_ID , RxTx_Data , &Rx_Data_Len, 
&Can_Rcv_Flags ) ; // receive message 

if ( (Rx ID = ID 1st) && Msg_Rcvd) { // if message received check id 
PORTB = RxTx_Data[ 0] ; // id correct, output data at PORTC 
RxTx_Data[ 0] ++; // increment received data 

CANSPIWrite (ID_2nd, RxTx_Data, 1, Can_Send_Flags ) ; // send 
incremented data back 
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Example of interfacing CAN transceiver MCP2510 with MCU via SPI interface 
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COMPACT FLASH LIBRARY 

The Compact Flash Library provides routines for accessing data on Compact Flash 
card (abbr. CF further in text). CF cards are widely used memory elements, com- 
monly used with digital cameras. Great capacity and excellent access time of only 
a few microseconds make them very attractive for microcontroller applications. 

In CF card, data is divided into sectors. One sector usually comprises 512 bytes. 
Routines for file handling, the cf Fat routines, are not performed directly but suc- 
cessively through 51 2B buffer. 

Note: Routines for file handling can be used only with FAT16 file system. 

Note: Library functions create and read files from the root directory only. 

Note: Library functions populate both FAT1 and FAT2 tables when writing to files, 
but the file data is being read from the FAT1 table only; i.e. there is no recovery if 
the FAT1 table gets corrupted. 

Note: If MMC/SD card has Master Boot Record (MBR), the library will work with the 
first available primary (logical) partition that has non-zero size. If MMC/SD card has 
Volume Boot Record (i.e. there is only one logical partition and no MBRs), the library 
works with entire card as a single partition. For more information on MBR, physical 
and logical drives, primary/secondary partitions and partition tables, please consult 
other resources, e.g. Wikipedia and similar. 

Note: Before writing operation, make sure not to overwrite boot or FAT sector as it 
could make your card on PC or digital camera unreadable. Drive mapping tools, 
such as Winhex, can be of great assistance. 
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The following variables 
must be defined in all 
projects using Compact 
Flash Library: 


Description: 


Example: 


extern sfr char 

CF Data Port; 


Compact Flash Data Port. 


char CF Data Port 
at PORTD; 


extern sfr sbit 

CF RDY; 


Ready signal line. 


sbit CF RDY at 

RB7 bit; 


extern sfr sbit 

CF WE; 


Write Enable signal line. 


sbit CF WE at 

RB6 bit; 


extern sfr sbit 

CF OE; 


Output Enable signal line. 


sbit CF OE at 

RB5 bit; 


extern sfr sbit 

CF CD1; 


Chip Detect signal line. 


sbit CF CD1 at 

RB4 bit; 


extern sfr sbit 

CF CE1; 


Chip Enable signal line. 


sbit CF CE1 at 

RB3 bit; 


extern sfr sbit 

CF A2; 


Address pin 2. 


sbit CF A2 at 

RB2 bit; 


extern sfr sbit 

CF Al; 


Address pin 1. 


sbit CF Al at 

RBI bit; 


extern sfr sbit 

CF AO; 


Address pin 0. 


sbit CF AO at 

RBO bit; 


extern sfr sbit 

CF RDY direction; 


Direction of the Ready pin. 


sbit CF RDY direc- 
tion at TRISB7 bit; 


extern sfr sbit 

CF WE direction; 


Direction of the Write Enable 
pin. 


sbit CF WE direction 
at TRISB6 bit; 


extern sfr sbit 

CF OE direction; 


Direction of the Output 
Enable pin. 


sbit CF OE direction 
at TRISB5 bit; 


extern sfr sbit 

CF CD1 direction; 


Direction of the Chip Detect 
pin. 


sbit CF CD1 direc- 
tion at TRISB4 bit; 


extern sfr sbit 

CF CE1 direction; 


Direction of the Chip Enable 
pin. 


sbit CF CE1 direc- 
tion at TRISB3 bit; 


extern sfr sbit 

CF A2 direction; 


Direction of the Address 2 
pin. 


sbit CF A2 direction 
at TRISB2 bit; 


extern sfr sbit 

CF Al direction; 


Direction of the Address 1 
pin. 


sbit CF Al direction 
at TRISB1 bit; 


extern sfr sbit 

CF AO direction; 


Direction of the Address 
pin. 


sbit CF AO direction 
at TRISBO bit; 
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Library Routines 

- Cfjnit 

- Cf_Detect 

- Cf_Enable 

- Cf_Disable 

- Cf_Read_lnit 

- CfReadByte 

- Cf_Write_lnit 

- Cf_Write_Byte 

- Cf_Read_Sector 

- Cf_Write_Sector 

Routines for file handling: 

- Cf_Fat_lnit 

- Cf_Fat_QuickFormat 

- Cf_Fat_Assign 

- Cf_Fat_Reset 

- CfFatRead 

- Cf_Fat_Rewrite 

- Cf_Fat_Append 

- Cf_Fat_Delete 

- Cf_Fat_Write 

- Cf_Fat_Set_File_Date 

- Cf_Fat_Get_File_Date 

- Cf_Fat_Get_File_Size 

- Cf_Fat_Get_Swap_File 

The following routine is for the internal use by compiler only: 

- Cf Issue ID Command 
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Cf Init 



Prototype 


void Cf Init () ; 


Returns 


Nothing. 


Description 


Initializes ports appropriately for communication with CF card. 




Global variables: 




- cf Data Port : Compact Flash data port 




- cf rdy : Ready signal line 




- cf we : Write enable signal line 




- cf oe : Output enable signal line 




- cf cdi : Chip detect signal line 




- cf cei : Enable signal line 




- cf A2 : Address pin 2 




- cf ai : Address pin 1 


Requires 


- cf ao : Address pin 




- cf rdy direction : Direction of the Ready pin 




- cf we direction : Direction of the Write enable pin 




- cf oe direction : Direction of the Output enable pin 




- cf cdi direction : Direction of the Chip detect pin 




- cf cei direction : Direction of the Chip enable pin 




- cf A2 direction : Direction of the Address 2 pin 




- cf ai direction : Direction of the Address 1 pin 




- cf ao direction : Direction of the Address pin 




must be defined before using this function. 




// set compact flash pinout 




char Cf Data Port at PORTD; 




sbit CF RDY at RB7 bit; 




sbit CF WE at RB6 bit; 




sbit CF OE at RB5 bit; 




sbit CF CDI at RB4 bit; 




sbit CF CEI at RB3 bit; 




sbit CF A2 at RB2 bit; 




sbit CF AI at RBI bit; 




sbit CF AO at RBO bit; 


Example 






sbit CF RDY direction at TRISB7 bit; 




sbit CF WE direction at TRISB6 bit; 




sbit CF OE direction at TRISB5 bit; 




sbit CF CDI direction at TRISB4 bit; 




sbit CF CEI direction at TRISB3 bit; 




sbit CF A2 direction at TRISB2 bit; 




sbit CF AI direction at TRISB1 bit; 




sbit CF AO direction at TRISBO bit; 




// end of compact flash pinout 




Cf Init(); // initialize CF 
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Cf Detect 



Prototype 


unsigned short Cf Detect (void) ; 


Returns 


- i - if CF card was detected 

- o - otherwise 


Description 


Checks for presence of CF card by reading the chip detect pin. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// Wait until CF card is inserted: 
do 

asm nop; 
while ( ! Cf_Detect ( ) ) ; 



Cf Enable 



Prototype 


void Cf Enable (void) ; 


Returns 


Nothing. 


Description 


Enables the device. Routine needs to be called only if you have disabled the 
device by means of the Cf_Disable routine. These two routines in conjunction 
allow you to free/occupy data line when working with multiple devices. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// enable compact flash 
Cf Enable () ; 



Cf Disable 



Prototype 


void Cf Disable (void) ; 


Returns 


Nothing. 


Description 


Routine disables the device and frees the data lines for other devices. To enable 
the device again, call Cf_Enable. These two routines in conjunction allow you to 
free/occupy data line when working with multiple devices. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// disable compact flash 
Cf Disable () ; 
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Cf Read Init 



Prototype 


void Cf Read Init (unsigned long address, unsigned short 

sector count ) ; 


Returns 


Nothing. 


Description 


Initializes CF card for reading. 
Parameters: 

- address: the first sector to be prepared for reading operation. 

- sector count: number of sectors to be prepared for reading operation. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// initialize compact flash for reading from sector 590 
Cf_Read_Init (590, 1); 



Cf_Read_Byte 



Prototype 


unsigned short Cf Read Byte (void) ; 


Returns 


Returns a byte read from Compact Flash sector buffer. 
Note: Higher byte of the unsigned return value is cleared. 


Description 


Reads one byte from Compact Flash sector buffer location currently pointed to 
by internal read pointers. These pointers will be autoicremented upon reading. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 

CF card must be initialized for reading operation. See Cf_Read_lnit. 


Example 


// Read a byte from compact flash: 
char data; 

data = Cf Read Byte ( ) ; 
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Cf Write Init 



Prototype 


void Cf Write Init (unsigned long address, unsigned short sectcnt); 


Returns 


Nothing. 


Description 


Initializes CF card for writing. 
Parameters: 

- address: the first sector to be prepared for writing operation. 

- sectcnt: number of sectors to be prepared for writing operation. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// initialize compact flash for writing to sector 590 
Cf Write Init (590, 1) ; 



Cf_Write_Byte 



Prototype 


void Cf Write Byte (unsigned short data ) ; 


Returns 


Nothing. 


Description 


Writes a byte to Compact Flash sector buffer location currently pointed to by 
writing pointers. These pointers will be autoicremented upon reading. When 
sector buffer is full, its contents will be transfered to appropriate flash memory 
sector. 

Parameters: 

- data : byte to be written. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 

CF card must be initialized for writing operation. See CfWritelnit. 


Example 


char data = OxAA; 
Cf Write Byte (data) ; 
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Cf Read Sector 



Prototype 


void Cf Read Sector (unsigned long sector number, unsigned short 

*buf f er ) ; 


Returns 


Nothing. 


Description 


Reads one sector (512 bytes). Read data is stored into buffer provided by the 
buffer parameter. 

Parameters: 

sector number: sector to be read. 

buffer: data buffer of at least 512 bytes in length. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// read sector 22 
unsigned short data[ 512] ; 

Cf Read Sector (22, data); 



Cf Write Sector 



Prototype 


void Cf Write Sector (unsigned long sector number, unsigned short 

*buf f er ) ; 


Returns 


Nothing. 


Description 


Writes 512 bytes of data provided by the buffer parameter to one CF sector. 
Parameters: 

- sector number: sector to be written to. 

- buffer: data buffer of 512 bytes in length. 


Requires 


The corresponding MCU ports must be appropriately initialized for CF card. See 
Cfjnit. 


Example 


// write to sector 22 
unsigned short data[ 512] ; 

Cf Write Sector (22, data); 
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Cf Fat Init 



Prototype 


unsigned short Cf Fat Init(); 


Returns 


- o - if CF card was detected and successfuly initialized 
1 - if FAT16 boot sector was not found 

- 255 - if card was not detected 


Description 


Initializes CF card, reads CF FAT16 boot sector and extracts necessary data 
needed by the library. 


Requires 


Nothing. 


Example 


// Init the FAT library 

if (!Cf Fat InitO) { // Init the FAT library 

} 



Cf Fat QuickFormat 



Prototype 


unsigned char Cf Fat QuickFormat (char * cf fat label); 


Returns 


- o if CF card was detected, successfuly formated and initialized 

- l - if FAT16 format was unseccessful 

- 255 - if card was not detected 


Description 


Formats to FAT16 and initializes CF card. 

Parameters: 

- cf fat label: volume label (11 characters in length). If less than 11 
characters are provided, the label will be padded with spaces. If null string is 
passed, the volume will not be labeled. 

Note: This routine can be used instead or in conjunction with CfFatlnit routine. 

Note: If CF card already contains a valid boot sector, it will remain unchanged 
(except volume label field) and only FAT and ROOT tables will be erased. Also, 
the new volume label will be set. 


Requires 


Nothing. 


Example 


// format and initialize the FAT library - 

if (!Cf Fat QuickFormat (&cf fat label)) { 

} 
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Cf_Fat_Assign 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned short Cf_Fat_Assign (char * filename, char f ile_cre_attr ) 



o if file does not exist and no new file is created. 

: if file already exists or file does not exist but a new file is created. 



Assigns file for file operations (read, write, delete...). All subsequent file opera- 
tions will be applied over the assigned file. 

Parameters: 

- filename: name of the file that should be assigned for file operations. The file name 
should be in DOS 8.3 (file_name.extension) format. The file name and extension will 
be automatically padded with spaces by the library if they have less than length 
required (i.e. "mikro.tx" -> "mikro .tx "), so the user does not have to take care of that. 
The file name and extension are case insensitive. The library will convert them to prop- 
er case automatically, so the user does not have to take care of that. 

Also, in order to keep backward compatibility with the first version of this library, 
file names can be entered as UPPERCASE string of 11 bytes in length with no 
dot character between the file name and extension (i.e. "MIKROELETXT" -> 
MIKROELE.TXT). In this case the last 3 characters of the string are considered 
to be file extension. 

- file ere attr: file creation and attributs flags. Each bit corresponds to the 
appropriate file attribut:: 



Bit 


Mask 


Description 





0x01 


Read Only 


1 


0x02 


Hidden 


2 


0x04 


System 


3 


0x08 


Volume Label 


4 


0x10 


Subdirectory 


5 


0x20 


Archive 


6 


0x40 


Device (internal use only, never found on disk) 


7 


0x80 


File creation flag. If the file does not exist and this flag is 
set, a new file with specified name will be created. 



Note: Long File Names (LFN) are not supported. 



CF card and CF library must be initialized for file operations. See CfFatlnit. 



// create file with archive attributes if it does not already exist 
Cf_Fat_Assign ("MIKRO 007 . TXT", OxAO) ; 
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Cf Fat Reset 



Prototype 


void Cf Fat Reset (unsigned long *size); 


Returns 


Nothing. 


Description 


Opens currently assigned file for reading. 

Parameters: 

- size: buffer to store file size to. After file has been open for reading its size is 
returned through this parameter. 


Requires 


CF card and CF library must be initialized for file operations. See Cf_Fat_lnit. 
File must be previously assigned. See Cf_Fat_Assign. 


Example 


unsigned long size; 
Cf Fat Reset (size) ; 



Cf Fat Read 



Prototype 


void Cf Fat Read (unsigned short *bdata); 


Returns 


Nothing. 


Description 


Reads a byte from currently assigned file opened for reading. Upon function exe- 
cution file pointers will be set to the next character in the file. 

Parameters: 

- bdata: buffer to store read byte to. Upon this function execution read byte is 
returned through this parameter. 


Requires 


CF card and CF library must be initialized for file operations. See CfFatlnit. 
File must be previously assigned. See Cf_Fat_Assign. 
File must be open for reading. See Cf_Fat_Reset. 


Example 


char character; 

Cf Fat Read ( Scharacter ) ; 
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Cf_Fat_Rewrite 






Prototype 


void Cf Fat Rewrite (); 






Returns 


Nothing. 






Description 


Opens currently assigned file for writing. If the file is not empty its content will be 
erased. 






Requires 


CF card and CF library must be initialized for file operations. See Cf_Fat_lnit. 
The file must be previously assigned. See Cf_Fat_Assign. 






Example 


// open file for writing 
Cf Fat Rewrite () ; 






Cf_Fat_Append 






Prototype 


void Cf Fat Append (); 






Returns 


Nothing. 






Description 


Opens currently assigned file for appending. Upon this function execution file 
pointers will be positioned after the last byte in the file, so any subsequent file writ- 
ing operation will start from there. 






Requires 


CF card and CF library must be initialized for file operations. See Cf_Fat_lnit. 
File must be previously assigned. See Cf_Fat_Assign. 






Example 


// open file for appending 
Cf Fat Append ( ) ; 






Cf_Fat_Delete 






Prototype 


void Cf Fat Delete (); 






Returns 


Nothing. 






Description 


Deletes currently assigned file from CF card. 






Requires 


CF card and CF library must be initialized for file operations. See Cf_Fat_lnit. 
File must be previously assigned. See Cf_Fat_Assign. 






Example 


// delete current file 
Cf Fat Delete () ; 
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Cf Fat Write 



Prototype 


void Cf Fat Write(char *fdata, unsigned data len); 


Returns 


Nothing. 


Description 


Writes requested number of bytes to currently assigned file opened for writing. 
Parameters: 

- fdata: data to be written. 

- data len: number of bytes to be written. 


Requires 


CF card and CF library must be initialized for file operations. See CfFatlnit. 

File must be previously assigned. See Cf_Fat_Assign. 

File must be open for writing. See Cf_Fat_Rewrite or Cf_Fat_Append. 


Example 


char file contents! 42] ; 

Cf Fat Write (file contents, 42); // write data to the assigned 
file 



Cf Fat Set File Date 



Prototype 


void Cf Fat Set File Date (unsigned int year, unsigned short 
month, unsigned short day, unsigned short hours, unsigned short 
mins, unsigned short seconds); 


Returns 


Nothing. 


Description 


Sets the date/time stamp. Any subsequent file writing operation will write this 
stamp to currently assigned file's time/date attributs. 

Parameters: 

- year: year attribute. Valid values: 1980-2107 

- month: month attribute. Valid values: 1-12 

- day: day attribute. Valid values: 1-31 

- hours: hours attribute. Valid values: 0-23 

- mins: minutes attribute. Valid values: 0-59 

- seconds: seconds attribute. Valid values: 0-59 


Requires 


CF card and CF library must be initialized for file operations. See Cf_Fat_lnit. 

File must be previously assigned. See Cf_Fat_Assign. 

File must be open for writing. See Cf_Fat_Rewrite or Cf_Fat_Append. 


Example 


Cf_Fat_Set_File_Date (2005, 9, 30, 17, 41,0); 
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Cf Fat Set File Date 



Prototype 


void Cf Fat Get File Date (unsigned int *year, unsigned short 
*month, unsigned short *day, unsigned short *hours, unsigned 
short *mins ) ; 


Returns 


Nothing. 


Description 


Reads time/date attributes of currently assigned file. 

Parameters: 

- year: buffer to store year attribute to. Upon function execution year attribute 
is returned through this parameter. 

- month: buffer to store month attribute to. Upon function execution month 
attribute is returned through this parameter. 

- day: buffer to store day attribute to. Upon function execution day attribute is 
returned through this parameter. 

- hours: buffer to store hours attribute to. Upon function execution hours 
attribute is returned through this parameter. 

- rains: buffer to store minutes attribute to. Upon function execution minutes 
attribute is returned through this parameter. 


Requires 


CF card and CF library must be initialized for file operations. See CfFatlnit. 
File must be previously assigned. See Cf_Fat_Assign. 


Example 


unsigned year; 

char month, day, hours, rains; 

Cf Fat Get File Date(&year, smonth, sday, Shours, Smins); 



Cf Fat Set File Size 



Prototype 


unsigned long Cf Fat Get File Size(); 


Returns 


Size of the currently assigned file in bytes. 


Description 


This function reads size of currently assigned file in bytes. 


Requires 


CF card and CF library must be initialized for file operations. See CfFatlnit. 
File must be previously assigned. See Cf_Fat_Assign. 


Example 


unsigned long my file size; 

my file size = Cf Fat Get File Size(); 
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Cf_Fat_Get_Swap_File 



Prototype 



Returns 



Description 



unsigned long Cf_Fat_Get_Swap_File (unsigned long sectors_cnt, 
char *filename, char file attr); 



■ Number of the start sector for the newly created swap file, if there was enough free space 
on CF card to create file of required size. 
- o otherwise 



This function is used to create a swap file of predefined name and size on the CF 
media. If a file with specified name already exists on the media, search for con- 
secutive sectors will ignore sectors occupied by this file. Therefore, it is recom- 
mended to erase such file if it exists before calling this function. If it is not erased 
and there is still enough space for a new swap file, this function will delete it after 
allocating new memory space for a new swap file. 

The purpose of the swap file is to make reading and writing to CF media as fast 
as possible, by using the Cf_Read_Sector() and Cf_Write_Sector() functions 
directly, without potentially damaging the FAT system. Swap file can be consid- 
ered as a "window" on the media where the user can freely write/read data. It's 
main purpose in the mikroC's library is to be used for fast data acquisition; when 
the time-critical acquisition has finished, the data can be re-written into a "normal" 
file, and formatted in the most suitable way. 

Parameters: 

- sectors cnt: number of consecutive sectors that user wants the swap file to have. 

- filename: name of the file that should be assigned for file operations. The file name 
should be in DOS 8.3 (file_name. extension) format. The file name and extension will 
be automatically padded with spaces by the library if they have less than length 
required (i.e. "mikro.tx" -> "mikro .tx "), so the user does not have to take care of that. 
The file name and extension are case insensitive. The library will convert them to 
proper case automatically, so the user does not have to take care of that. Also, in order 
to keep backward compatibility with the first version of this library, file names can be 
entered as UPPERCASE string of 11 bytes in length with no dot chsaracter between 
the file name and extension (i.e. "MIKROELETXT" -> MIKROELE.TXT). In this case 
the last 3 characters of the string are considered to be file extension. 

file attr: file creation and attributs flags. Each bit corresponds to the 
appropriate file attribut: 



Bit 


Mask 


Description 





0x01 


Read Only 


1 


0x02 


Hidden 


2 


0x04 


System 


3 


0x08 


Volume Label 


4 


0x10 


Subdirectory 


5 


0x20 


Archive 


6 


0x40 


Device (internal use only, never found on disk) 


7 


0x80 


Not used 



Note: Long File Names (LFN) are not supported. 
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Requires 


CF card and CF library must be initialized for file operations. See Cf_Fat_lnit. 




// Try to create a swap file with archive 




atribute, whose size will be at least 1000 sectors. 




// If it succeeds, it sends the No. of start sector over UART 




unsigned long size; 




size = Cf Fat Get Swap File (1000, "mikroE.txt", 0x20); 


Example 


if (size) { 

UART Write (OxAA) ; 




UART Write (Lo (size) ) ; 




UART Write (Hi (size) ) ; 




UART Write (Higher (size) ) ; 




UART Write (Highest (size) ) ; 




UART Write (OxAA) ; 



Library Example 

The following example demonstrates various aspects of the Cf_Fat16 library: Creation of new file 
and writing down to it; Opening existing file and re-writing it (writing from start-of-file); Opening 
existing file and appending data to it (writing from end-of-file); Opening a file and reading data from 
it (sending it to USART terminal); Creating and modifying several files at once; 

// set compact flash pinout 
char Cf Data Port at PORTD; 



sbit CF_RDY 
sbit CF_WE 
sbit CF_OE 
sbit CF_CD1 
sbit CF_CE1 
sbit CF_A2 
sbit CF_A1 
sbit CF A0 



at RB7_bit; 
at RB6_bit; 
at RB5_bit; 
at RB4_bit; 
at RB3_bit; 
at RB2_bit; 
at RBl_bit; 
at RB0 bit; 



sbit CF_RDY_direction 
sbit CF_WE_direction 
sbit CF_OE_direction 
sbit CF_CDl_direction 
sbit CF_CEl_direction 
sbit CF_A2_direction 
sbit CF_Al_direction 
sbit CF_A0_direction 
// end of cf pinout 



at TRI 
at TRI 
at TRI 
at TRI 
at TRI 
at TRI 
at TRI 
at TRI 



SB7_bit; 
SB6_bit; 
SB5_bit; 
SB4_bit; 
SB3_bit; 
SB2_bit; 
SBlJoit; 
SB0 bit; 



const LINE_LEN = 39; 

char err_txt[ 2 0] = "FAT16 not found"; 

char file contents! LINE LEN] = "XX CF FAT16 library by Anton Rieckertn"; 
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char filename! 14] = "MIKRO00x.TXT"; // File names 

unsigned short loop, loop2; 

unsigned long i, size; 

char Buffer! 512] ; 

// UART1 write text and new line (carriage return + line feed) 
void UARTl_Write_Line (char *uart_text) { 

UARTl_Write_Text (uart_text) ; 

UARTl_Write (13) ; 

UARTl_Write (10) ; 
} 

// Creates new file and writes some data to it 
void M_Create_New_File ( ) { 
filename! 7] = 'A' ; 

Cf Fat Assign ( {.filename, OxAO); // Find existing file or create a 
new one 

Cf Fat Rewrite (); // To clear file and start with new data 
for (loop = 1; loop <= 99; loop++) { 
UARTl_Write ('.'); 

file_contents[ 0] = loop / 10 + 48; 
file_contents[ 1] = loop % 10 + 48; 
Cf_Fat_Write (file_contents, LINE_LEN-1); // write data to the 
assigned file 

} 
} 

// Creates many new files and writes data to them 
void M_Create_Multiple_Files ( ) { 

for(loop2 = 'B'; loop2 <= ' Z ' ; loop2++) { 

UARTl^Write (loop2 ) ; // signal the progress 

filename! 7] = loop2; // set filename 

Cf Fat Assign ( sfilename, OxAO); // find existing file or create 
a new one 

Cf Fat Rewrite (); // To clear file and start with new data 
for (loop = 1; loop <= 44; loop++) { 
file_contents[ 0] = loop / 10 + 48; 
f ile_contents[ 1] = loop % 10 + 48; 

Cf_Fat_Write (file_contents, LINE_LEN-1); // write data to the 
assigned file 



// Opens an existing file and rewrites it 
void M_Open_File_Rewrite ( ) { 

filename! 7] = 'C; 

Cf Fat Assign ( sfilename, 0); 

Cf_Fat_Rewrite () ; 

for (loop = 1; loop <= 55; loop++) { 
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f ile_contents[ 0] = loop / 10 + 65; 
f ile_contents[ 1] = loop % 10 + 65; 
Cf_Fat_Write (f ile_contents, LINE_LEN-1) ; 
assigned file 



// write data to the 



} 

// Opens an existing file and appends data to it 
// (and alters the date/time stamp) 

void M_Open_File_Append () { 

filename! 7] = ' B ' ; 

Cf Fat Assign ( sfilename, 0); 

Cf_Fat_Set_File_Date (2005, 6, 21, 10,35, 0); 

Cf Fat_Append ( ) ; // Prepare file for append 

Cf_Fat_Write (" for mikroElektronika 2005n", 27); // Write data to 
assigned file 



// Opens an existing file, reads data from it and puts it to UART 
void M_Open_File_Read () { 
char character; 

filename! 7] = ' B ' ; 
Cf Fat Assign ( sfilename, 0); 

Cf_Fat_Reset ( Ssize) ; // To read file, procedure returns size of file 
for (i = 1; i <= size; i + + ) { 

Cf _Fat_Read ( Scharacter ) ; 

UART1 Write (character) ; // Write data to UART 



// Deletes a file. If file doesn't exist, it will first be created 
// and then deleted. 
void M_Delete_File () { 

filename! 7] = ' F ' ; 

Cf Fat Assign (filename, 0); 

Cf Fat Delete () ; 
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// Tests whether file exists, and if so sends its creation date 
// and file size via UART 
void M_Test_File_Exist () { 

unsigned long fsize; 

unsigned int year; 

unsigned short month, day, hour, minute; 

unsigned char outstr[ 12] ; 

filename! 7] = ' B ' ; //uncomment this line to search for file that 
DOES exists 

// filename! 7] = 'F'; //uncomment this line to search for file that 
DOES NOT exist 
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if (Cf_Fat_Assign (filename, 0)) { 

// file has been found - get its date 

Cf Fat Get File Date(&year, smonth, &day, shour, sminute); 

WordToStr (year, outstr); 

UARTl_Write_Text (outstr) ; 

ByteToStr (month, outstr); 

UARTl_Write_Text (outstr) ; 

WordToStr (day, outstr); 

UARTl_Write_Text (outstr) ; 

WordToStr (hour, outstr); 

UARTl_Write_Text (outstr) ; 

WordToStr (minute, outstr); 

UARTl_Write_Text (outstr) ; 

// get file size 

fsize = Cf_Fat_Get_File_Size () ; 

LongToStr ( (signed long) fsize, outstr); 

UARTl_Write_Line (outstr) ; 
} 
else { 

// file was not found - signal it 

UARTl_Write (0x55) ; 

Delayjns (1000) ; 

UARTl_Write (0x55) ; 
} 
} 

// Tries to create a swap file, whose size will be at least 100 
// sectors (see Help for details) 
void M_Create_Swap_File () { 
unsigned int i; 

for(i=0; i<512; i++) 
Buffer[ i] = i; 

size = Cf_Fat_Get_Swap_File (5000, "mikroE.txt", 0x20); // see help 
on this function for details 

if (size) { 

LongToStr ( (signed long) size, errtxt) ; 
UARTl_Write_Line (err_txt) ; 

for(i=0; i<5000; i++) { 

Cf_Write_Sector (size++, Buffer) ; 
UART1 Write ('.'); 



// Main. Uncomment the function (s) to test the desired operation (s) 
void main ( ) { 

fdefine COMPLETE_EXAMPLE // comment this line to make sim- 
pler/smaller example 
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// Configure AN pins as digital 
// Turn off comparators 



ADC0N1 |= OxOF; 
CMCON | = 7 ; 

// Initialize UART1 module 
UARTl_Init (19200) ; 
Delayjns (10) ; 



UARTl_Write_Line ("PIC-Started") ; // PIC present report 

// use fatl6 quick format instead of init routine if a formatting 
is needed 

if (Cf_Fat_Init() == 0) { 

Delay_ms (2000 ) ; // wait for a while until the card is stabilized 
// period depends on used CF card 

// Test start 

UARTl_Write_Line ("Test Start. ") ; 

// Test routines. Uncomment them one-by-one to test certain 

features 

M_Create_New_File ( ) ; 
#ifdef COMPLETE_EXAMPLE 

M_Create_Multiple_Files () ; 
M_Open_File_Rewrite () ; 
M_Open_File_Append ( ) ; 
M_Open_File_Read ( ) ; 
M_Delete_File () ; 
M_Test_File_Exist () ; 
M_Create_Swap_File ( ) ; 
#endif 
UART1 Write Line ("Test End."); 



else { 

UARTl_Write_Line (err_txt) ; // Note: Cf_Fat_Init tries to initial- 
ize a card more than once. 

// If card is not present, initializa- 
tion may last longer (depending on clock speed) 
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HW Connection 




Pin diagram of CF memory card 
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EEPROM LIBRARY 

EEPROM data memory is available with a number of PIC MCUs. mikroC PRO for PIC includes 
library for comfortable work with EEPROM. 

Library Routines 

- EepromRead 

- Eeprom_Write 

EEPROM Read 



Prototype 


unsigned short EEPROM Read (unsigned int address); 


Returns 


Returns byte from specified address. 


Description 


Reads data from specified address. Parameter address is of integer type, 
which means it supports MCUs with more than 256 bytes of EEPROM. 


Requires 


Requires EEPROM module. 

Ensure minimum 20ms delay between successive use of routines 

eeprom write and eeprom Read. Although PIC will write the correct value, 
eeprom Read might return an undefined result. 


Example 


unsigned short take; 

take = EEPROM Read(0x3F); 



EEPROM Write 



Prototype 


void EEPROM Write (unsigned int address, unsigned short data); 


Returns 


Nothing. 


Description 


Writes data to specified address. Parameter address is of integer type, which 
means it supports MCUs with more than 256 bytes of EEPROM. 
Be aware that all interrupts will be disabled during execution of eeprom write 
routine (GIE bit of INTCON register will be cleared). Routine will restore previ- 
ous state of this bit on exit. 


Requires 


Requires EEPROM module. 

Ensure minimum 20ms delay between successive use of routines 

eeprom write and eeprom Read. Although PIC will write the correct value, 
eeprom Read might return an undefined result. 


Example 


EEPROM Write (0x32, 19); 
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Library Example 

The example demonstrates use of EEPROM Library. 



char i i ; 

void main () { 
ANSEL = 

ANSELH 



0; 
0; 



// loop variable 

// Configure AN pins as digital I/O 



PORTB 
PORTC 
PORTD 

TRISB 
TRISC 
TRISD 



// Fill data buffer 

// Write data to address 0x80+ii 

// Write some data at address 2 

// Write some data at address 0150 

// Blink PORTB and PORTC diodes 

// to indicate reading start 



for(ii = 0; ii < 32; ii++) 

EEPROM_Write (0x80+ii, ii) 

EEPROM_Write (0x02, OxAA) ; 
EEPROM_Write (0x50, 0x55) ; 

Delayjns (1000) ; 
PORTB = OxFF; 
PORTC = OxFF; 
Delayjns (1000) ; 
PORTB = 0x00; 
PORTC = 0x00; 
Delayjns (1000) ; 

PORTB = EEPROM_Read(0x02) ; 
display it on PORTB 

PORTC = EEPROM_Read(0x50) ; 
display it on PORTC 

Delayjns (1000) ; 



for(ii = 0; ii < 32; ii++) { // Read 32 bytes block from address 0x80 
PORTD = EEPROM_Read (0x80 + ii) ; // and display data on PORTD 
Delayjns (250) ; 



// Read data from address 2 and 
// Read data from address 0x50 and 
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ETHERNET PIC18FXXJ60 LIBRARY 

pici8Fxxj60 family of microcontrollers feature an embedded Ethernet controller module. This is 
a complete connectivity solution, including full implementations of both Media Access Control 
(MAC) and Physical Layer transceiver (PHY) modules. Two pulse transformers and a few passive 
components are all that are required to connect the microcontroller directly to an Ethernet net- 
work. 

The Ethernet module meets all of the IEEE 802.3 specifications for 10-BaseT connectivity to a 
twisted-pair network. It incorporates a number of packet filtering schemes to limit incoming pack- 
ets. It also provides an internal DMA module for fast data throughput and hardware assisted IP 
checksum calculations. Provisions are also made for two LED outputs to indicate link and network 
activity 

This library provides the posibility to easily utilize ethemet feature of the above mentioned MCUs. 

Ethernet PIC18FxxJ60 library supports: 

- IPv4 protocol. 

- ARP requests. 

- ICMP echo requests. 

- UDP requests. 

- TCP requests (no stack, no packet reconstruction). 

- ARP client with cache. 

- DNS client. 

- UDP client. 

- DHCP client. 

- packet fragmentation is NOT supported. 

Note: Global library variable EthernetuserTimerSec is used to keep track of time for all client 
implementations (ARP, DNS, UDP and DHCP). It is user responsibility to increment this variable 
each second in it's code if any of the clients is used. 

Note: For advanced users there are header files ("eth j60LibDef.h" and 
"eth_j60LibPrivate.h") in Uses\P18 folder of the compiler with description of all routines and 
global variables, relevant to the user, implemented in the Ethernet PIC18FxxJ60 Library. 
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Library Routines 

- Ethemetjnit 

- Ethernet_Enable 

- Ethernet_Disable 

- EthernetdoPacket 

- Ethernet_putByte 

- Ethernet_putBytes 

- Ethernet_putString 

- Ethernet_putConstString 

- Ethernet_putConstBytes 

- Ethernet_getByte 

- Ethernet_getBytes 

- EthemetUserTCP 

- EthemetUserUDP 

- EthemetgetlpAddress 

- Ethernet_getGwlpAddress 

- EthemetgetDnslpAddress 

- Ethernet_getlpMask 

- Ethernet_confNetwork 

- Ethernet_arpResolve 

- EthemetsendUDP 

- Ethernet_dnsResolve 

- Ethernet_initDHCP 

- EthemetdoDHCPLeaseTime 

- Ethernet renewDHCP 
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Ethernet Init 



Prototype 



Returns 



Description 



Requires 



Example 



void Ethernetlnit (unsigned char *mac, unsigned char *ip, 
unsigned char fullDuplex) ; 



Nothing. 



This is MAC module routine. It initializes Ethernet controller. This function is 
internaly splited into 2 parts to help linker when coming short of memory. 

Ethernet controller settings (parameters not mentioned here are set to default): 

- receive buffer start address : Oxoooo. 

- receive buffer end address : 0x19ad. 

- transmit buffer start address: 0x19ae. 

- transmit buffer end address : Oxifff. 

- RAM buffer read/write pointers in auto-increment mode. 

- receive filters set to default: CRC + MAC Unicast + MAC Broadcast in OR 
mode. 

- flow control with TX and RX pause frames in full duplex mode. 

- frames are padded to 60 bytes + CRC. 

- maximum packet size is set to 1518. 

- Back-to-Back Inter-Packet Gap: 0xi5 in full duplex mode; 0xi2 in half duplex 
mode. 

- Non-Back-to-Back Inter-Packet Gap: 0x0012 in full duplex mode; 0x0ci2 in 
half duplex mode. 

- half duplex loopback disabled. 

- LED configuration: default (LEDA-link status, LEDB-link activity). 

Parameters: 

- mac: RAM buffer containing valid MAC address. 

- ip: RAM buffer containing valid IP address. 

■ fullDuplex: ethernet duplex mode switch. Valid values: o (half duplex 
mode) and l (full duplex mode). 

Note: If a DHCP server is to be used, IP address should be set to o . o . o . o. 



Nothing. 



#define Ethernet_HALFDUPLEX 
#define Ethernet_FULLDUPLEX 1 

unsigned char myMacAddr[ 6] = { 0x00, 0x14, 0xA5, 0x76, 0x19, 

0x3f} ; // my MAC address 

unsigned char mylpAddr = { 192, 168, 1, 60 } ; // my IP addr 

Ethernet_Init (myMacAddr, mylpAddr, Ethernet_FULLDUPLEX) ; 
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Ethernet Enable 



Prototype 



Returns 



Description 



void Ethernet_Enable (unsigned char enFlt) ; 



Nothing. 



This is MAC module routine. This routine enables appropriate network traffic on 
the MCU's internal Ethernet module by the means of it's receive filters (unicast, 
multicast, broadcast, crc). Specific type of network traffic will be enabled if a 
corresponding bit of this routine's input parameter is set. Therefore, more than 
one type of network traffic can be enabled at the same time. For this purpose, 
predefined library constants (see the table below) can be ORed to form appro- 
priate input value. 

Parameters: 

- enFit: network traffic/receive filter flags. Each bit corresponds to the appro- 
priate network traffic/receive filter: 



Bi 
t 


Mask 


Description 


Predefined library 
const 





0x01 


MAC Broadcast traffic/receive filter flag. When 
set, MAC broadcast traffic will be enabled. 


Ethernet BROADCAST 


1 


0x02 


MAC Multicast traffic/receive filter flag. When 
set, MAC multicast traffic will be enabled. 


Ethernet MULTICAST 


2 


0x04 


not used 


none 


3 


0x08 


not used 


none 


4 


0x10 


not used 


none 


5 


0x20 


CRC check flag. When set, packets with 
invalid CRC field will be discarded. 


Ethernet CRC 


6 


0x40 


not used 


none 


7 


0x80 


MAC Unicast traffic/receive filter flag. When 
set, MAC unicast traffic will be enabled. 


Ethernet UNICAST 



Note: Advance filtering available in the MCU's internal Ethernet module such as 

Pattern Match, Magic Packet and Hash Table can not be enabled by this 

routine. Additionaly, all filters, except CRC, enabled with this routine will work in 
OR mode, which means that packet will be received if any of the enabled filters 
accepts it. 

Note: This routine will change receive filter configuration on-the-fly. It will not, in 
any way, mess with enabling/disabling receive/transmit logic or any other part of 
the MCU's internal Ethernet module. The MCU's internal Ethernet module should 
be properly cofigured by the means of Ethemetjnit routine. 
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Requires 



Example 



Ethernet module has to be initialized. See Ethernet Init. 



Ethernet_Enable (_Ethernet_CRC | _Ethernet_UNICAST) ; // enable 
CRC checking and Unicast traffic 



Ethernet Disable 



Prototype 



Returns 



Description 



void Ethernet_Enable (unsigned char enFlt) ; 



Nothing. 



This is MAC module routine. This routine disables appropriate network traffic on the 
MCU's internal Ethernet module by the means of it's receive filters (unicast, multicast, 
broadcast, crc). Specific type of network traffic will be disabled if a corresponding bit 
of this routine's input parameter is set. Therefore, more than one type of network traf- 
fic can be disabled at the same time. For this purpose, predefined library constants 
(see the table below) can be ORed to form appropriate input value. 

Parameters: 

- disFit: network traffic/receive filter flags. Each bit corresponds to the appro- 
priate network traffic/receive filter: 



Bit 


Mask 


Description 


Predefined library 
const 





0x01 


MAC Broadcast traffic/receive filter flag. When 
set, MAC broadcast traffic will be disabled. 


Ethernet BROADCAST 


1 


0x02 


MAC Multicast traffic/receive filter flag. When 
set, MAC multicast traffic will be disabled. 


Ethernet MULTICAST 


2 


0x04 


not used 


none 


3 


0x08 


not used 


none 


4 


0x10 


not used 


none 


5 


0x20 


CRC check flag. When set, CRC check will 

be disabled and packets with invalid CRC 

field will be accepted. 


Ethernet CRC 


6 


0x40 


not used 


none 


7 


0x80 


MAC Unicast traffic/receive filter flag. When 
set, MAC unicast traffic will be disabled. 


Ethernet UNICAST 



Note: Advance filtering available in the MCU's internal Ethernet module such as 
Pattern Match, Magic Packet and Hash Table can not be disabled by this routine. 
Note: This routine will change receive filter configuration on-the-fly. It will not, in 
any way, mess with enabling/disabling receive/transmit logic or any other part of 
the MCU's internal Ethernet module. The MCU's internal Ethernet module 
should be properly cofigured by the means of Ethemetjnit routine. 
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Requires 



Example 



Ethernet module has to be initialized. See Ethernet Init. 



Ethernet_Disable (_Ethernet_CRC | _Ethernet_UNICAST) ; // disable 
CRC checking and Unicast traffic 



Ethernet doPacket 



Prototype 


unsigned char Ethernet doPacket (); 


Returns 


- upon successful packet processing (zero packets received or received 
packet processed successfuly). 

1 - upon reception error or receive buffer corruption. Ethernet controller 
needs to be restarted. 

- 2 - received packet was not sent to us (not our IP, nor IP broadcast address). 

- 3 - received IP packet was not IPv4. 

- 4 - received packet was of type unknown to the library. 


Description 


This is MAC module routine. It processes next received packet if such exists. 
Packets are processed in the following manner: 

- ARP & ICMP requests are replied automatically. 

- upon TCP request the EthemetUserTCP function is called for further processing. 

- upon UDP request the Ethemet_UserUDP function is called for further processing. 

Note: Ethernet doPacket must be called as often as possible in user's code. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


if (Ethernet doPacket () == 0) { // process received packets 
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Ethernet_putByte 



Prototype 


void Ethernet putByte (unsigned char v) ; 


Returns 


Nothing. 




This is MAC module routine. It stores one byte to address pointed by the cur- 




rent Ethernet controller's write pointer (ewrpt). 


Description 


Parameters: 




- v: value to store 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 




char data; 


Example 


Ethernet putByte (data) ; // put an byte into Ethernet controller's 




buffer 



Ethernet_putBytes 



Prototype 


void Ethernet putBytes (unsigned char *ptr, unsigned char n) ; 


Returns 


Nothing. 


Description 


This is MAC module routine. It stores requested number of bytes into Ethernet 
controller's RAM starting from current Ethernet controller's write pointer (ewrpt) 
location. 

Parameters: 

- ptr: RAM buffer containing bytes to be written into Ethernet controller's RAM. 

- n: number of bytes to be written. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


char * buffer = "mikroElektronika" ; 

Ethernet putBytes (buffer, 16); // put an RAM array into Ethernet 
controller's buffer 
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Ethernet_putConstBytes 



Prototype 


void Ethernet putConstBytes (const unsigned char *ptr, unsigned 
char n) ; 


Returns 


Nothing. 


Description 


This is MAC module routine. It stores requested number of const bytes into Eth- 
ernet controller's RAM starting from current Ethernet controller's write pointer 
(ewrpt) location. 

Parameters: 

- ptr: const buffer containing bytes to be written into Ethernet controller's RAM. 

- n: number of bytes to be written. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


const char *buffer = "mikroElektronika"; 

Ethernet putConstBytes (buffer, 16); // put a const array into 
Ethernet controller's buffer 



Ethernet_putString 



Prototype 


unsigned int Ethernet putString (unsigned char *ptr) ; 


Returns 


Number of bytes written into Ethernet controller's RAM. 


Description 


This is MAC module routine. It stores whole string (excluding null termination) into 
Ethernet controller's RAM starting from current Ethernet controller's write pointer 
(ewrpt) location. 

Parameters: 

- ptr: string to be written into Ethernet controller's RAM. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


char * buffer = "mikroElektronika"; 

Ethernet putString (buff er) ; // put a RAM string into Ethernet 
controller's buffer 
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Ethernet_putConstString 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned int Ethernet_putConstString (const unsigned char *ptr) ; 



Number of bytes written into Ethernet controller's RAM. 



This is MAC module routine. It stores whole const string (excluding null termina- 
tion) into Ethernet controller's RAM starting from current Ethernet controller's 
write pointer (ewrpt) location. 
Parameters: 
- ptr: const string to be written into Ethernet controller's RAM. 



Ethernet module has to be initialized. See Ethernet Init. 



const char * buffer 



'mikroElektronika' 



Ethernet putConstString (buf f er ) ; // put a const string into 
Ethernet controller's buffer 



Ethernet_getByte 



Prototype 


unsigned char Ethernet getByteO; 


Returns 


Byte read from Ethernet controller's RAM. 


Description 


This is MAC module routine. It fetches a byte from address pointed to by current 
Ethernet controller's read pointer (erdpt). 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


char buffer; 

buffer = Ethernet getByteO; // read a byte from Ethernet con- 
troller's buffer 



Ethernet_getBytes 



Prototype 


void Ethernet getBytes (unsigned char *ptr, unsigned int addr, 
unsigned char n) ; 


Returns 


Nothing. 


Description 


This is MAC module routine. It fetches equested number of bytes from Ethernet 
controller's RAM starting from given address. If value of OxFFFF is passed as 
the address parameter, the reading will start from current Ethernet controller's 
read pointer (ERDPT) location. 
Parameters: 

- ptr: buffer for storing bytes read from Ethernet controller's RAM. 

- addr: Ethernet controller's RAM start address. Valid values: 0..8192. 

- n: number of bytes to be read. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


char buffer[ 16] ; 

Ethernet getBytes (buf fer, 0x100, 16); // read 16 bytes, starting 
from address 0x100 
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Ethernet UserTCP 



Prototype 


unsigned int Ethernet UserTCP (unsigned char * remoteHost, unsigned 
int remotePort, unsigned int localPort, unsigned int reqLength); 


Returns 


- o - there should not be a reply to the request. 

- Length of TCP/HTTP reply data field - otherwise. 


Description 


This is TCP module routine. It is internally called by the library. The user access- 
es to the TCP/HTTP request by using some of the Ethernet_get routines. The 
user puts data in the transmit buffer by using some of the Ethernet_put routines. 
The function must return the length in bytes of the TCP/HTTP reply, or if there 
is nothing to transmit. If there is no need to reply to the TCP/HTTP requests, just 
define this function with return(O) as a single statement. 

Parameters: 

- remoteHost: client's IP address. 

- remotePort: client's TCP port. 

- localPort: port to which the request is sent. 

- reqLength: TCP/HTTP request data field length. 

Note: The function source code is provided with appropriate example projects. 
The code should be adjusted by the user to achieve desired reply. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


This function is internally called by the library and should not be called by the 
user's code. 
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Ethernet UserUDP 



Prototype 


unsigned int Ethernet UserUDP (unsigned char * remoteHost, unsigned 
int remotePort, unsigned int destPort, unsigned int reqLength) ; 


Returns 


- o - there should not be a reply to the request. 

- Length of UDP reply data field - otherwise. 


Description 


This is UDP module routine. It is internally called by the library. The user access- 
es to the UDP request by using some of the Ethernet_get routines. The user puts 
data in the transmit buffer by using some of the Ethernet_put routines. The func- 
tion must return the length in bytes of the UDP reply or if nothing to transmit. If 
you don't need to reply to the UDP requests, just define this function with a 
return(O) as single statement. 

Parameters: 

- remoteHost: client's IP address. 

- remotePort: client's port. 

- destPort: port to which the request is sent. 

- reqLength: UDP request data field length. 

Note: The function source code is provided with appropriate example projects. 
The code should be adjusted by the user to achieve desired reply. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


This function is internally called by the library and should not be called by the user's code. 



Ethernet_getlpAddress 



Prototype 


unsigned char * Ethernet getlpAddress () ; 


Returns 


Ponter to the global variable holding IP address. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned IP address. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own IP address buffer. These locations should not be altered 
by the user in any case! 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char ipAddr[ 4] ; // user IP address buffer 

memcpy (ipAddr , Ethernet getlpAddress () , 4); // fetch IP address 
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Ethernet_getGwlpAddress 



Prototype 


unsigned char * Ethernet getGwIpAddress () ; 


Returns 


Ponter to the global variable holding gateway IP address. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned gateway IP address. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own gateway IP address buffer. These locations should not be 
altered by the user in any case! 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char gwIpAddr[ 4] ; // user gateway IP address buffer 

memcpy (gwIpAddr, Ethernet getGwIpAddress () , 4); // fetch gateway 
IP address 



Ethernet_getDnslpAddress(); 



Prototype 


unsigned char * Ethernet getDnsIpAddress 


Returns 


Ponter to the global variable holding DNS IP address. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned DNS IP address. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own DNS IP address buffer. These locations should not be 
altered by the user in any case! 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char dnsIpAddr[ 4] ; // user DNS IP address buffer 

memcpy (dnsIpAddr, Ethernet getDnsIpAddress () , 4); // fetch DNS 
server address 
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Ethernet_getlpMask 



Prototype 


unsigned char * Ethernet getIpMask() 


Returns 


Ponter to the global variable holding IP subnet mask. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned IP subnet mask. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own IP subnet mask buffer. These locations should not be 
altered by the user in any case! 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char IpMask[ 4] ; // user IP subnet mask buffer 

memcpy (IpMask, Ethernet getIpMask(), 4); // fetch IP subnet mask 



Ethernet confNetwork 



Prototype 


void Ethernet confNetwork (char *ipMask, char *gwIpAddr, char 
* dnsIpAddr ) ; 


Returns 


Nothing. 


Description 


Configures network parameters (IP subnet mask, gateway IP address, DNS IP 
address) when DHCP is not used. 

Parameters: 

- ipMask: IP subnet mask. 

- gwipAddr gateway IP address. 

- dnsipAddr: DNS IP address. 

Note: The above mentioned network parameters should be set by this routine 
only if DHCP module is not used. Otherwise DHCP will override these settings. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char ipMask[ 4] = { 255, 255, 255, } ; // network 
mask (for example : 255.255.255.0) 

unsigned char gwIpAddr[ 4] = { 192, 168, 1, 1 } ; // gateway 
(router) IP address 

unsigned char dnsIpAddr[ 4] = { 192, 168, 1, 1 } ; // DNS serv- 
er IP address 

Ethernet confNetwork (ipMask, gwipAddr, dnsipAddr) ; // set network 
configuration parameters 
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Ethernet_arpResolve 



Prototype 


unsigned char * Ethernet arpResolve (unsigned char *ip, unsigned 
char tmax) ; 


Returns 


- MAC address behind the IP address - the requested IP address was resolved. 

- o - otherwise. 


Description 


This is ARP module routine. It sends an ARP request for given IP address and waits for 
ARP reply. If the requested IP address was resolved, an ARP cash entry is used for stor- 
ing the configuration. ARP cash can store up to 3 entries. For ARP cash structure refer to 
"eth j60LibDef .h" header file in the compiler's Uses/P1 8 folder. 

Parameters: 

- ip: IP address to be resolved. 

- tmax: time in seconds to wait for an reply. 

Note: The Ethernet services are not stopped while this routine waits for ARP 
reply. The incoming packets will be processed normaly during this time. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


Ethernet arpResolve ( IpAddr, 5); // get MAC address behind the 
above IP address, wait 5 sees for the response 



Ethernet sendUDP 



Prototype 


unsigned char Ethernet sendUDP (unsigned char *destIP, unsigned 
int sourcePort, unsigned int destPort, unsigned char *pkt, 
unsigned int pktLen) ; 


Returns 


- i - UDP packet was sent successfully. 

- o - otherwise. 


Description 


This is UDP module routine. It sends an UDP packet on the network. 

Parameters: 

- destip: remote host IP address. 

- sourcePort: local UDP source port number. 

- destPort: destination UDP port number. 

- pkt: packet to transmit. 

- pktLen: length in bytes of packet to transmit. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char IpAddr[ 4] = { 192, 168, 1, 1 } ; // remote IP address 

Ethernet sendUDP (IpAddr, 10001, 10001, "Hello", 5); // send Hello mes- 
sage to the above IP address, from UDP port 10001 to UDP port 10001 
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Ethernet dnsResolve 



Prototype 


unsigned char *Ethernet dnsResolve (unsigned char *host, unsigned 
char tmax) ; 


Returns 


- pointer to the location holding the IP address - the requested host name was 
resolved. 

- o - otherwise. 


Description 


This is DNS module routine. It sends an DNS request for given host name and 
waits for DNS reply. If the requested host name was resolved, it's IP address is 
stored in library global variable and a pointer containing this address is returned 
by the routine. UDP port 53 is used as DNS port. 

Parameters: 

- host: host name to be resolved. 

■ tmax: time in seconds to wait for an reply. 

Note: The Ethernet services are not stopped while this routine waits for DNS 
reply. The incoming packets will be processed normaly during this time. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own resolved host IP address buffer. These locations should 
not be altered by the user in any case! 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


unsigned char * remoteHostIpAddr[ 4] ; // user host IP address buffer 

// SNTP server: 

// Zurich, Switzerland: Integrated Systems Lab, Swiss Fed. Inst, of 

Technology 

// 129.132.2.21: swisstime.ethz.ch 

// Service Area: Switzerland and Europe 

memcpy (remoteHostlpAddr, Ethernet dnsResolve ("swisstime.ethz.ch", 5), 4); 
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Ethernet initDHCL 



Prototype 


unsigned char Ethernet initDHCP (unsigned char tmax) ; 


Returns 


i - network parameters were obtained successfuly. 
- o - otherwise. 


Description 


This is DHCP module routine. It sends an DHCP request for network parameters 
(IP, gateway, DNS addresses and IP subnet mask) and waits for DHCP reply. If 
the requested parameters were obtained successfuly, their values are stored into 
the library global variables. 

These parameters can be fetched by using appropriate library IP get routines: 

- EthernetgetlpAddress - fetch IP address. 

- EthernetgetGwIpAddress - fetch gateway IP address. 

- EthernetgetDnslpAddress - fetch DNS IP address. 

- Ethernet_getlpMask - fetch IP subnet mask. 

UDP port 68 is used as DHCP client port and UDP port 67 is used as DHCP serv- 
er port. 

Parameters: 

- tmax: time in seconds to wait for an reply. 

Note: The Ethernet services are not stopped while this routine waits for DNS 
reply. The incoming packets will be processed normaly during this time. 

Note: When DHCP module is used, global library variable 
Ethernet userTimerSec is used to keep track of time. It is user responsibility to 
increment this variable each second in it's code. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


Ethernet initDHCP (5) ; // get network configuration from DHCP server, 
wait 5 sec for the response 
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Ethernet doDHCPLeaseTime 



Prototype 


unsigned char Ethernet doDHCPLeaseTime () ; 


Returns 


- o - lease time has not expired yet. 

- 1 - lease time has expired, it's time to renew it. 


Description 


This is DHCP module routine. It takes care of IP address lease time by decre- 
menting the global lease time library counter. When this time expires, it's time to 
contact DHCP server and renew the lease. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


while (1) { 

if (Ethernet doDHCPLeaseTime ( ) ) 

... // it's time to renew the IP address lease 
} 



Ethernet renewDHCP 



Prototype 


unsigned char Ethernet renewDHCP (unsigned char tmax); 


Returns 


- o - upon success (lease time was renewed). 

- l - otherwise (renewal request timed out). 


Description 


This is DHCP module routine. It sends IP address lease time renewal request to 
DHCP server. 

Parameters: 

- tmax: time in seconds to wait for an reply. 


Requires 


Ethernet module has to be initialized. See Ethemetjnit. 


Example 


if (Ethernet doDHCPLeaseTime ( ) ) 

Ethernet renewDHCP ( 5 ) ; // it's time to renew the IP address lease, 
with 5 sees for a reply 

} 
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Library Example 

This code shows how to use the PIC18FxxJ60 Ethernet library: 

- the board will reply to ARP & ICMP echo requests 

- the board will reply to UDP requests on any port : 

returns the request in upper char with a header made of remote host IP & 
port number 

- the board will reply to HTTP requests on port 80, GET method with pathnames : 

/ will return the HTML main page 

/s will return board status as text string 

/to ... IU will toggle RDO to RD7 bit and return HTML main page 

all other requests return also HTML main page. 

#define _Ethernet_HALFDUPLEX 
#define Ethernet_FULLDUPLEX 1 

* ROM constant strings 
*/ 

const unsigned char httpHeader[ ] = "HTTP/1.1 200 OKnContent-type : " 

// HTTP header 
const unsigned char httpMimeTypeHTML[ ] = "text/htmlnn" ; 
// HTML MIME type 

const unsigned char httpMimeTypeScript[ ] = "text/plainnn" ; 
// TEXT MIME type 

unsigned char httpMethod[ ] = "GET /"; 
/* 

* web page, splited into 2 parts : 

* when coming short of ROM, fragmented data is handled more effi- 
ciently by linker 

* this HTML page calls the boards to get its status, and builds 
itself with javascript 

*/ 
const char *indexPage = // Change the IP address of the page to 
be refreshed 

"<meta http-equiv=" re fresh" content=" 3; url=http : //l 92 .168 .20. 60 "> 
<HTMLXHEADX/HEADXBODY> 
<hl>PIC18FxxJ60 Mini Web Server</hl> 
<a href=/>Reload</a> 
<script src=/sX/script> 

<tablextrxtd valign=top><table border=l style = "f ont-size : 20px 
; font-family : terminal ; "> 
<tr><th colspan=2>ADC</thX/tr> 

<trXtd>AN2</tdXtdXscript> document .write (AN2 )< /scrip tx/tdx/tr> 
<tr><td>AN3</tdxtdXscript> document .write (AN3 )< /scrip tx/tdx/tr> 
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</table></tdxtd>< table border=l style="f ont-size : 20px ; font-family : 

terminal ; "> 

<tr><th colspan=2>P0RTB</thX/tr> 

<script> 

var str,i; 

str=""; 

for (i=0;i<8;i + + ) 

{ str+="<tr><td bgcolor=pink>BUTTON #"+i+"</td> " ; 

if (PORTBS (l«i) ){ str+="<td bgcolor=red>ON" ;} 

else { str+="<td bgcolor=#cccccc>OFF" ;} 

str+="</tdX/tr>";} 

document .write (str) ; 

</script> 



const char * indexPage2 = "</table></tdxtd> 

<table border=l style="f ont-size : 20px ; font-family : terminal ; "> 

<tr><th colspan=3>P0RTD</thX/tr> 

<script> 

var str,i; 

str="" ; 

for (i=0;i<3;i++) 

{ str+="<trxtd bgcolor=yellow>LED # " + i + "</td> " ; 

if (PORTD& (l«i) ){ str+="<td bgcolor=red>ON" ;} 

else { str+="<td bgcolor=#cccccc>OFF" ;} 

str+="</tdxtd><a href=/t" + i+">Toggle</a></tdx/tr> " ;} 

document .write (str ) ; 

</script> 

</table></tdx/trX/table> 

This is HTTP request 

#<script>document. write (REQ) </script></BODYX/HTML> 



* RAM variables 
*/ 
unsigned char myMacAddr[ 6] = { 0x00, 0x14, 0xA5, 0x76, 0x19, 0x3f} 
// my MAC address 

unsigned char myIpAddr[ 4] = {192, 168, 
// my IP address 
unsigned char gwIpAddr[ 4] = { 192, 168, 20, 6 

(router) IP address 
unsigned char ipMask[ 4] = { 255, 255, 255, } ; 

(for example : 255.255.255.0) 

unsigned char dnsIpAddr[ 4] = { 192, 168, 
// DNS server IP address 



20, 60 } ; 

; // gateway 

// network mask 

20, 1 } ; 



unsigned char 
unsigned char 
unsigned long 



getRequest[ 15] ; // HTTP request buffer 
dyna[ 30] ; // buffer for dynamic response 
httpCounter = 0; // counter of HTTP requests 
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* functions 

*/ 
/* 

* put the constant string pointed to by s to the Ethernet con- 
troller's transmit buffer. 

*/ 
/*unsigned int putConstString (const char *s) 
{ 
unsigned int ctr = ; 

while (* s ) 

{ 

Ethernet_putByte (*s++) ; 

ctr++; 

} 
return (ctr) ; 
}*/ 
/* 

* it will be much faster to use library Ethernet putConstString rou- 
tine 

* instead of putConstString routine above. However, the code will 
be a little 

* bit bigger. User should choose between size and speed and pick the 
implementation that 

* suites him best. If you choose to go with the putConstString def- 
inition above 

* the #define line below should be commented out. 
* 

*/ 

#define putConstString Ethernet putConstString 

/* 

* put the string pointed to by s to the Ethernet controller's trans- 
mit buffer 

*/ 
/♦unsigned int putString (char *s) 
{ 
unsigned int ctr = ; 

while (* s ) 
{ 
Ethernet_putByte (*s++) ; 

ctr++; 

} 
return (ctr) ; 
}*/ 

:_ 
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* it will be much faster to use library Ethernet_j?utString routine 

* instead of putString routine above. However, the code will be a 
little 

* bit bigger. User should choose between size and speed and pick the 
implementation that 

* suites him best. If you choose to go with the putString defini- 
tion above 

* the fdefine line below should be commented out. 
* 

*/ 

#define putString Ethernet putString 

/* 

* this function is called by the library 

* the user accesses to the HTTP request by successive calls to 
Ethernet_getByte () 

* the user puts data in the transmit buffer by successive calls to 
Ethernet jputByte () 

* the function must return the length in bytes of the HTTP reply, 
or if nothing to transmit 

* if you don't need to reply to HTTP requests, 

* just define this function with a return (0) as single statement 
* 

*/ 
unsigned int Ethernet_UserTCP (unsigned char *remoteHost, unsigned 
int remotePort, unsigned int localPort, unsigned int reqLength) 



{ 

unsigned int len 

unsigned char i; 



0; 



// my reply length 

// general purpose char 



if (localPort != 80) //I listen only to web request on port 80 
{ 

return ( ) ; 
} 

// get 10 first bytes only of the request, the rest does not 
matter here 

for(i = 0; i < 10; i++) 
{ 

getRequest[ i] = Ethernet_getByte () ; 
} 
getRequest[ 10] = 0; 

if (memcmp (getRequest, httpMethod, 5))// only GET method is 
supported here 

{ 

return ( ) ; 

} 
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httpCounter++; // one more request done 

if (getRequest[ 5] == ' s ' ) //if request path name starts with 
s, store dynamic data in transmit buffer 
{ 

// the text string replied by this request can be 
interpreted as javascript statements 
// by browsers 

len = putConstString (httpHeader) ; // HTTP header 
len += putConstString (httpMimeTypeScript) ; // with 
text MIME type 

// add AN2 value to reply 

IntToStr (ADC_Read(2) , dyna); 

len += putConstString ( "var AN2="); 

len += putString (dyna) ; 

len += putConstString (";") ; 

// add AN3 value to reply 

IntToStr (ADC_Read (3) , dyna); 

len += putConstString ( "var AN3="); 

len += putString (dyna) ; 

len += putConstString (";") ; 

// add PORTS value (buttons) to reply 
len += putConstString ("var PORTB="); 
IntToStr (PORTB, dyna); 
len += putString (dyna) ; 
len += putConstString (";") ; 

// add PORTD value (LEDs) to reply 
len += putConstString ("var PORTD="); 
IntToStr (PORTD, dyna); 
len += putString (dyna) ; 
len += putConstString (";") ; 

// add HTTP requests counter to reply 
IntToStr (httpCounter, dyna); 
len += putConstString ("var REQ="); 
len += putString (dyna) ; 
len += putConstString (";") ; 
} 
else if (getRequest[ 5] == 't') //if request path name starts 
with t, toggle PORTD (LED) bit number that comes after 
{ 

unsigned char bitMask = 0; // for bit mask 
if (isdigit (getRequest[ 6] ) ) // if <= bit number < = 
9, bits 8 & 9 does not exist but does not matter 
{ 
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bitMask = getRequest[ 6] - '0'; // convert ASCII to integer 
bitMask = 1 << bitMask; // create bit mask 
PORTD A = bitMask; // toggle PORTD with xor operator 



} 



} 



if (len 



0) 



// what do to by default 



f 



len = putConstString (httpHeader) ; // HTTP header 
len += putConstString (httpMimeTypeHTML) ; // with HTML MIME type 
len += putConstString (indexPage) ; // HTML page first part 
len += putConstString (indexPage2) ; // HTML page second part 



return (len); // return to the library with the number of 
bytes to transmit 



/* 

* this function is called by the library 

* the user accesses to the UDP request by successive calls to 
Ethernet_getByte () 

* the user puts data in the transmit buffer by successive calls to 
Ethernet_putByte () 

* the function must return the length in bytes of the UDP reply, or 
if nothing to transmit 

■k 

* if you don't need to reply to UDP requests, 

* just define this function with a return (0) as single statement 



*/ 
unsigned int Ethernet_UserUDP (unsigned char *remoteHost, unsigned 
int remotePort, unsigned int destPort, unsigned int reqLength) 



{ 

unsigned int len; 



// my reply length 



// reply is made of the remote host IP address in human read- 
able format 

ByteToStr (remoteHost[ 0] , dyna);// first IP address byte 

dyna[ 3] = 

ByteToStr (remoteHost[ 1] , dyna + 4); // second 

dyna[ 7] = 

ByteToStr (remoteHost[ 2] , dyna + 8); // third 

dyna[ 11] = 

ByteToStr (remoteHost[ 3] , dyna + 12); // fourth 



dyna[ 15] 



// add separator 



// then remote host port number 
WordToStr (remotePort, dyna + 16); 
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dyna[ 21] = '[ '; 

WordToStr (destPort, dyna + 22); 

dyna[ 2 7] = '] ' ; 

dyna[ 2 8] = 0; 

// the total length of the request is the length of the 
dynamic string plus the text of the request 
len = 28 + reqLength; 

// puts the dynamic string into the transmit buffer 
Ethernet_putBytes (dyna, 28); 

// then puts the request string converted into upper char 
into the transmit buffer 

while (reqLength--) 
{ 

Ethernet_putByte (toupper (Ethernet_getByte ( ) ) ) ; 
} 

return(len); // back to the library with the length of the 
UDP reply 
} 

/* 

* main entry 
*/ 
void main ( ) 
{ 

ADC0N1 = OxOB; // ADC convertors will be used with AN2 and AN3 
CMCON = 0x07; // turn off comparators 

PORTA = 0; 

TRISA = Oxfc; // set PORTA as input for ADC 

// except RAO and RA1 which will be used as 
// ethernet's LEDA and LEDB 

// set PORTB as input for buttons 

// set PORTD as output 

/* 

* Initialize Ethernet controller 

*/ 
Ethernet_Init (myMacAddr, mylpAddr, Ethernet_FULLDUPLEX) ; 

//dhcp will not be used here, so use preconf igured addresses 
Ethernet confNetwork (ipMask, gwIpAddr, dnsIpAddr) ; 

MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 31 9 



PORTB 


= 


0; 




TRISB 


= 


Ox 


:ff; 


PORTD 


= 


0; 




TRISD 


= 


0; 
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while (1) // do forever 

{ 
/* 

* if necessary, test the return value to get error code 
*/ 
Ethernet doPacket(); // process incoming Ethernet packets 

/* 

* add your stuff here if needed 

* Ethernet_doPacket ( ) must be called as often as possible 

* otherwise packets could be lost 
*/ 

} 
} 



320 MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



CHAPTER 7 
mikroC PRO for PIC Libraries 

FLASH MEMORY LIBRARY 

This library provides routines for accessing microcontroller Flash memory. Note that 
prototypes differ for PIC1 6 and PIC1 8 families. 

Note: Due to the P16/P18 family flash specifics, flash library is MCU dependent. 
Since the P18 family differ significantlly in number of bytes that can be erased 
and/or written to specific MCUs, the appropirate suffix is added to the names of 
functions in order to make it easier to use them. Flash memory operations are MCU 
dependent : 

1 . Read operation supported. For this group of MCU's only read function is imple 
mented. 

2. Read and Write operations supported (write is executed as erase-and-write). For 
this group of MCU's read and write functions are implemented. Note that write 
operation which is executed as erase-and-write, may write less bytes than it 
erases. 

3. Read, Write and Erase operations supported. For this group of MCU's read, 
write and erase functions are implemented. Further more, flash memory block 
has to be erased prior to writting (write operation is not executed as erase-and- 
write). 

Please refer to MCU datasheet before using flash library. 

Library Routines 



FLASH 


Read 






FLASH 


Read 


NBytes 


FLASH 


Write 






FLASH 


Write 


8 




FLASH 


Write 


16 




FLASH 


Write 


32 




FLASH 


Write 


64 




FLASH 


Erase 






FLASH 


Erase 


64 




FLASH 


Erase 


1024 




FLASH 


Erase 


Write 




FLASH 


Erase 


Write 


64 


FLASH 


Erase 


Write 


1024 
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FLASH Read 



Prototype 


unsigned FLASH Read (unsigned address); 

// for PIC18 

unsigned short FLASH Read(long address) ; 


Returns 


Returns data byte from Flash memory. 


Description 


Reads data from the specified address in Flash memory. 


Requires 


Nothing. 


Example 


// for PIC18 
unsigned short tmp; 

tmp = FLASH Read ( OxODOO ) ; 



FLASH_Read_N_Bytes 



Prototype 



void FLASH_Read_N_Bytes (long address, char* data_, unsigned int N) ; 



Returns 



Nothing. 



Description 



Reads N data from the specified address in Flash memory to varibale pointed by 



dat; 



Requires 



Nothing. 



Example 



FLASH Read N (OxODOO, data buffer, sizeof (data buffer)) 
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FLASH Write 



Prototype 


// for PIC16 

void FLASH Write (unsigned address, unsigned int* data) ; 

II for PIC18 

void FLASH Write 8 (long address, char* data); 

void FLASH Write 16 (long address, char* data); 

void FLASH Write 32 (long address, char* data); 

void FLASH Write 64 (long address, char* data); 


Returns 


Nothing. 


Description 


Writes block of data to Flash memory. Block size is MCU dependent. 

P16: This function may erase memory segment before writing block of data to it 
(MCU dependent). Furthermore, memory segment which will be erased may be 
greater than the size of the data block that will be written (MCU dependent). 
Therefore it is recommended to write as many bytes as you erase. FLASH_Write 
writes 4 flash memory locations in a row, so it needs to be called as many times 
as it is necessary to meet the size of the data block that will be written. 

P18: This function does not perform erase prior to write. 


Requires 


Flash memory that will be written may have to be erased before this function is 
called (MCU dependent). Refer to MCU datasheet for details. 


Example 


Write consecutive values in 64 consecutive locations, starting from OxODOO: 

unsigned short toWrite[ 64] ; 

// initialize array: 
for (i = 0; i < 64; i++) 
toWrite[ i] = i; 

// write contents of the array to the address OxODOO: 
FLASH Write 64 (OxODOO, toWrite) ; 
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FLASH Erase 



Prototype 


// for PIC16 

void FLASH Erase (unsigned address); 

// for PIC18 

void FLASH Erase 64 (long address); 

void FLASH Erase 1024 (long address); 


Returns 


Nothing. 


Description 


Erases memory block starting from a given address. For P1 6 familly is implement- 
ed only for those MCU's whose flash memory does not support erase-and-write 
operations (refer to datasheet for details). 


Requires 


Nothing. 


Example 


Erase 64 byte memory memory block, starting from address OxODOO: 

FLASH Erase 64 (OxODOO); 



FLASH Erase Write 



Prototype 


// for PIC18 

void FLASH Erase Write 64 (long address, char* data) ; 

void FLASH Erase Write 1024 (long address, char* data); 


Returns 


None. 


Description 


Erase then write memory block starting from a given address. 


Requires 


Nothing. 


Example 


char toWrite[ 64] ; 
int i; 

// initialize array: 

for(i=0; i<64; i + + ) toWrite[ i] =i; 

// erase block of memory at address OxODOO then write contents of 
the array to the address OxODOO: 
FLASH Erase Write 64 (OxODOO, toWrite); 
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Library Example 

The example demonstrates simple write to the flash memory for PIC16F887, then 
reads the data and displays it on PORTB and PORTC. 



char i = ; 

unsigned int addr, data_, 

0x3FAA+2, 0x3FAA+3} , 

0x3FAA+6, 0x3FAA+7} , 

0x3FAA+10, 0x3FAA+ll} , 

0x3FAA+14, 0x3FAA+15} } ; 

void main ( ) { 
ANSEL = 0; 
ANSELH = 0; 
PORTB = 0; 
TRISB = 0; 
PORTC = 0; 
TRISC = 0; 
Delay_ms (500) ; 



dataAR[ 4] [ 4] 



{{ 0x3FAA+0, 0x3FAA+l, 

{ 0x3FAA+4, 0x3FAA+5, 

{ 0x3FAA+8, 0x3FAA+9, 

{ 0x3FAA+12, 0x3FAA+13, 



// Configure AN pins as digital I/O 



// Initial PORTB value 

// Set PORTB as output 

// Initial PORTC value 

// Set PORTC as output 



// All block writes 

// to program memory are done as 16-word erase by 
// eight-word write operations. The write operation is 
// edge-aligned and cannot occur across boundaries. 
// Therefore it is recommended to perform flash writes in 16-word 
chunks . 

// That is why lower 4 bits of start address [ 3:0] must be zero. 
// Since FLASH Write routine performs writes in 4-word chunks, 
// we need to call it 4 times in a row. 

addr = 0x0430; // starting Flash address, valid for P16F887 
for (i = 0; i < 4; i + + ){ // Write some data to Flash 

Delayjns (100) ; 

FLASH_Write (addr+i*4, dataAR[ i] ) ; 
} 
Delayjns (500) ; 



addr = 0x0430; 

for (i = 0; i < 16; i++){ 

data_ = FLASH_Read(addr++) 

Delay_us (10) ; 

PORTB = data_; 

PORTC = data_ » 8; 

Delay_ms (500) ; 



// P16's FLASH is 14-bit wide, so 
// two MSB's will always be '00' 
// Display data on PORTB LS Byte 
// and PORTC MS Byte 
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GRAPHIC LCD LIBRARY 

The mikroC PRO for PIC provides a library for operating Graphic Led 128x64 (with 
commonly used Samsung KS108/KS107 controller). 

For creating a custom set of Glcd images use Glcd Bitmap Editor Tool. 

External dependencies of Graphic LCD Library 



The following variables must 

be defined in all projects 
using Graphic LCD Library: 


Description: 


Example: 


extern sfr char 

GLCD DataPort; 


Glcd Data Port. 


char GLCD DataPort at 
PORTD; 


extern sfr sbit 

GLCD CS1; 


Chip Select 1 line. 


RBO bit; 


extern sfr sbit 

GLCD CS2; 


Chip Select 2 line. 


RBI bit; 


extern sfr sbit 

GLCD RS; 


Register select line. 


RB2 bit; 


extern sfr sbit 

GLCD RW; 


Read/Write line. 


RB3 bit; 


extern sfr sbit 

GLCD EN; 


Enable line. 


RB4 bit; 


extern sfr sbit 

GLCD RST; 


Reset line. 


RB5 bit; 


extern sfr sbit 

GLCD CS1 Direction; 


Direction of the Chip 
Select 1 pin. 


sbit GLCD CS1 Direction 
at TRLSBO bit; 


extern sfr sbit 

GLCD CS2 Direction; 


Direction of the Chip 
Select 2 pin. 


sbit GLCD CS2 Direction 
at TRISB1 bit; 


extern sfr sbit 

GLCD RS Direction; 


Direction of the Regis- 
ter select pin. 


sbit GLCD RS Direction 
at TRISB2 bit; 


extern sfr sbit 

GLCD RW Direction; 


Direction of the 
Read/Write pin. 


sbit GLCD RW Direction 
at TRLSB3 bit; 


extern sfr sbit 

GLCD EN Direction; 


Direction of the Enable 
pin. 


sbit GLCD EN Direction 
at TRISB4 bit; 


extern sfr sbit 

GLCD RST Direction; 


Direction of the Reset 
pin. 


sbit GLCD RST Direction 
at TRISB5 bit; 
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Library Routines 

Basic routines: 

- Glcdjnit 

- Glcd_Set_Side 

- Glcd_Set_X 

- GlcdSetPage 

- GlcdReadData 

- Glcd_Write_Data 

Advanced routines: 

- Glcd_Fill 

- Glcd_Dot 

- GlcdJJne 

- Glcd_V_Line 

- Glcd_H_Line 

- GlcdRectangle 

- GlcdBox 

- Glcd_Circle 

- GlcdSetFont 

- Glcd_Write_Char 

- Glcd_Write_Text 

- Glcdlmage 
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Glcd Init 



Prototype 


void Glcd Init () ; 


Returns 


Nothing. 


Description 


Initializes the Glcd module. Each of the control lines is both port and pin config- 
urable, while data lines must be on a single port (pins <0:7>). 


Requires 


Global variables: 

- glcd csi: Chip select 1 signal pin 

- glcd cs2: Chip select 2 signal pin 

- glcd rs: Register select signal pin 

- glcd rw: Read/Write Signal pin 

- glcd en: Enable signal pin 

- glcd rst: Reset signal pin 

- glcd DataPort: Data port 

- glcd csi Direction: Direction of the Chip select 1 pin 

- glcd cs2 Direction: Direction of the Chip select 2 pin 

- glcd rs Direction: Direction of the Register select signal pin 

- glcd rw Direction: Direction of the Read/Write signal pin 

- glcd en Direction: Direction of the Enable signal pin 
-glcd rst Direction: Direction of the Reset signal pin 

must be defined before using this function. 


Example 


// glcd pinout settings 
char GLCD DataPort at PORTD; 

sbit GLCD CSI at RBO bit; 
sbit GLCD CS2 at RBI bit; 
sbit GLCD RS at RB2 bit; 
sbit GLCD RW at RB3 bit; 
sbit GLCD EN at RB4 bit; 
sbit GLCD RST at RB5 bit; 

sbit GLCD CSI Direction at TRISBO bit; 
sbit GLCD CS2 Direction at TRISB1 bit; 
sbit GLCD RS Direction at TRISB2 bit; 
sbit GLCD RW Direction at TRISB3 bit; 
sbit GLCD EN Direction at TRISB4 bit; 
sbit GLCD RST Direction at TRISB5 bit; 

ANSEL = 0; 
ANSELH = 0; 
Glcd Init () ; 
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Glcd Set Side 



Prototype 


void Glcd Set Side (unsigned short x pos); 


Returns 


Nothing. 


Description 


Selects Glcd side. Refer to the Glcd datasheet for detailed explaination. 

Parameters: 

- x pos: position on x-axis. Valid values: 0..127 

The parameter xpos specifies the Glcd side: values from to 63 specify the 
left side, values from 64 to 127 specify the right side. 

Note: For side, x axis and page layout explanation see schematic at the bottom 
of this page. 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. 


Example 


The following two lines are equivalent, and both of them select the left side of 
Glcd: 

Glcd Select Side (0) ; 
Glcd_Select_Side (10) ; 



Glcd Set X 



Prototype 


void Glcd Set X (unsigned short x pos); 


Returns 


Nothing. 


Description 


Sets x-axis position to x pos dots from the left border of Glcd within the select- 
ed side. 

Parameters: 

- x pos: position on x-axis. Valid values: 0..63 

Note: For side, x axis and page layout explanation see schematic at the bottom 
of this page. 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. 


Example 


Glcd Set X (25) ; 
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Glcd_Set_Page 




Prototype 


void Glcd Set Page (unsigned short page); 


Returns 


Nothing. 




Selects page of the Glcd. 






Parameters: 




Description 


- page: page number. Valid values: 0..7 






Note: For side, x axis and page layout explanation see schematic at the 


bottom 




of this page. 




Requires 


GLCD needs to be initialized, see Glcdjnit routine. 


Example 


Glcd Set Page (5) ; 



Glcd Read Data 



Prototype 


unsigned short Glcd Read Data(); 


Returns 


One byte from GLCD memory. 


Description 


Reads data from from the current location of Glcd memory and moves to the 
next location. 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. 

Glcd side, x-axis position and page should be set first. See functions 
Glcd_Set_Side, GlcdSetX, and GlcdSetPage. 


Example 


unsigned short data; 
data = Glcd Read DataO; 



330 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 7 
Libraries 



Glcd Write Data 



Prototype 


void Glcd Write Data (unsigned short ddata); 


Returns 


Nothing. 




Writes one byte to the current location in Glcd memory and moves to the next 
location. 


Description 


Parameters: 




- ddata: data to be written 




Glcd needs to be initialized, see Glcdjnit routine. 


Requires 


Glcd side, x-axis position and page should be set first. See functions 
GlcdSetSide, GlcdSetX, and GlcdSetPage. 


Example 


unsigned short data; 
Glcd Write Data (data); 



Glcd Fil 



Prototype 


void Glcd Fill (unsigned short pattern) ; 


Returns 


Nothing. 


Description 


Fills Glcd memory with the byte pattern. 

Parameters: 

- pattern: byte to fill Glcd memory with 

To clear the Glcd screen, use Glcd Fill (0) . 

To fill the screen completely, use Glcd Fill (Oxff) . 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. 


Example 


// Clear screen 
Glcd Fill (0) ; 
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Glcd Dot 



Prototype 


void Glcd Dot (unsigned short x pos, unsigned short y pos, 
unsigned short color) ; 


Returns 


Nothing. 


Description 


Draws a dot on Glcd at coordinates (x_pos, y_pos). 
Parameters: 

- x pos: x position. Valid values: 0..127 

- y pos: y position. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines a dot state: clears dot, 1 puts a dot, and 2 
inverts dot state. 

Note: For x and y axis layout explanation see schematic at the bottom of this 
page. 


Requires 


Glcd needs to be initialized, see Glcdlnit routine. 


Example 


// Invert the dot in the upper left corner 
Glcd_Dot(0, 0, 2); 



Glcd Line 



Prototype 


void Glcd Line (int x start, int y start, int x end, int y end, 
unsigned short color) ; 


Returns 


Nothing. 


Description 


Draws a line on Glcd. 
Parameters: 

- x start: x coordinate of the line start. Valid values: 0..127 

- y start: y coordinate of the line start. Valid values: 0..63 

- x end: x coordinate of the line end. Valid values: 0..127 

- y end: y coordinate of the line end. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the line color: white, 1 black, and 2 inverts 
each dot. 


Requires 


Glcd needs to be initialized, see Glcdlnit routine. 


Example 


// Draw a line between dots (0,0) and (20,30) 
Glcd_Line(0, 0, 20, 30, 1); 
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Glcd V Line 



Prototype 


void Glcd V Line (unsigned short y start, unsigned short y end, 
unsigned short x pos, unsigned short color) ; 


Returns 


Nothing. 


Description 


Draws a vertical line on Glcd. 
Parameters: 

- y start: y coordinate of the line start. Valid values: 0..63 

- y end: y coordinate of the line end. Valid values: 0..63 

- x pos: x coordinate of vertical line. Valid values: 0..127 

- color: color parameter. Valid values: 0..2 

The parameter color determines the line color: white, 1 black, and 2 inverts 
each dot. 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. 


Example 


// Draw a vertical line between dots (10,5) and (10,25) 
Glcd V Line (5, 25, 10, 1); 



Glcd H Line 



Prototype 


void Glcd H Line (unsigned short x start, unsigned short x end, 
unsigned short y pos, unsigned short color) ; 


Returns 


Nothing. 


Description 


Draws a horizontal line on Glcd. 
Parameters: 

- x start: x coordinate of the line start. Valid values: 0..127 
-x end: x coordinate of the line end. Valid values: 0..127 

- y pos: y coordinate of horizontal line. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the line color: white, 1 black, and 2 inverts 
each dot. 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. 


Example 


// Draw a horizontal line between dots (10,20) and (50,20) 
Glcd H LinedO, 50, 20, 1); 
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Glcd_Rectangle 



Prototype 


void Glcd Rectangle (unsigned short x upper left, unsigned short 
y upper left, unsigned short x bottom right, unsigned short 
y bottom right, unsigned short color) ; 


Returns 


Nothing. 


Description 


Draws a rectangle on GLCD. 
Parameters: 

- x upper left: x coordinate of the upper left rectangle corner. Valid values: 0..127 

- y upper left: y coordinate of the upper left rectangle corner. Valid values: 0..63 

- x bottom right: x coordinate of the lower right rectangle corner. Valid 
values: 0..127 

- y bottom right: y coordinate of the lower right rectangle corner. Valid 
values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the rectangle border: white, 1 
black, and 2 inverts each dot. 


Requires 


GLCD needs to be initialized, see Glcdjnit routine. 


Example 


// Draw a rectangle between dots (5,5) and (40,40) 
Glcd Rectangle (5, 5, 40, 40, 1); 



Glcd Box 



Prototype 


void Glcd Box (unsigned short x upper left, unsigned short 
y upper left, unsigned short x bottom right, unsigned short 
y bottom right, unsigned short color) ; 


Returns 


Nothing. 


Description 


Draws a box on GLCD. 

Parameters: 

- x upper left: x coordinate of the upper left box corner. Valid values: 0..127 

- y upper left: y coordinate of the upper left box corner. Valid values: 0..63 

- x bottom right: x coordinate of the lower right box corner. Valid values: 0..127 

- y bottom right: y coordinate of the lower right box corner. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the box fill: white, 1 black, and 2 
inverts each dot. 


Requires 


GLCD needs to be initialized, see Glcdjnit routine. 


Example 


// Draw a box between dots (5,15) and (20,40) 
Glcd_Box(5, 15, 20, 40, 1); 
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Glcd Circle 



Prototype 


void Glcd Circle (int x center, int y center, int radius, unsigned 
short color) ; 


Returns 


Nothing. 


Description 


Draws a circle on GLCD. 
Parameters: 

- x center: x coordinate of the circle center. Valid values: 0..127 

- y center: y coordinate of the circle center. Valid values: 0..63 

- radius: radius size 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the circle line: white, 1 black, 
and 2 inverts each dot. 


Requires 


GLCD needs to be initialized, see Glcdlnit routine. 


Example 


// Draw a circle with center in (50,50) and radius=10 
Glcd_Circle (50, 50, 10, 1); 



Glcd Set Font 



Prototype 


void Glcd Set Font (const char *activeFont, unsigned short 
aFontWidth, unsigned short aFontHeight, unsigned int aFontOffs) ; 


Returns 


Nothing. 


Description 


Sets font that will be used with Glcd_Write_Char and Glcd_Write_Text routines. 
Parameters: 

- activeFont: font to be set. Needs to be formatted as an array of byte 

- aFontwidth: width of the font characters in dots. 

- aFontHeight: height of the font characters in dots. 

- aFontot f s: number that represents difference between the mikroC PRO for 
PIC character set and regular ASCII set (eg. if 'A' is 65 in ASCII character, and 
'A' is 45 in the mikroC PRO for PIC character set, aFontOffs is 20). Demo 
fonts supplied with the library have an offset of 32, which means that they start 
with space. 

The user can use fonts given in the file " Lib_GLCDFonts" file located in the 

Uses folder or create his own fonts. 


Requires 


GLCD needs to be initialized, see Glcd Init routine. 


Example 


// Use the custom 5x7 font "myfont" which starts with space (32) : 
Glcd Set Font (Smyfont, 5, 7, 32); 
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Glcd Write Char 



Prototype 


void Glcd Write Char (unsigned short chr, unsigned short x pos, 
unsigned short page num, unsigned short color) ; 


Returns 


Nothing. 


Description 


Prints character on the GLCD. 
Parameters: 

- chr : character to be written 

- x pos : character starting position on x-axis. Valid values: 0..(127-FontWidth) 

- page num : the number of the page on which character will be written. Valid 
values: 0..7 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the character: white, 1 black, 
and 2 inverts each dot. 

Note: For x axis and page layout explanation see schematic at the bottom of 
this page. 


Requires 


Glcd needs to be initialized, see Glcdjnit routine. Use Glcd_Set_Font to speci- 
fy the font for display; if no font is specified, then default 5x8 font supplied with 
the library will be used. 


Example 


// Write character 'C' on the position 10 inside the page 2: 
Glcd Write Char('C', 10, 2, 1); 
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Glcd Write Text 



Prototype 


void Glcd Write Text (char *text, unsigned short x pos, unsigned 
short page num, unsigned short color) ; 


Returns 


Nothing. 


Description 


Prints text on GLCD. 

Parameters: 

- text: text to be written 

- x pos: text starting position on x-axis. 

- page num: the number of the page on which text will be written. Valid values: 0..7 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the text: white, 1 black, and 2 
inverts each dot. 

Note: For x axis and page layout explanation see schematic at the bottom of 
this page. 


Requires 


Glcd needs to be initialized, see Glcdlnit routine. Use Glcd_Set_Font to specify 
the font for display; if no font is specified, then default 5x8 font supplied with the 
library will be used. 


Example 


// Write text "Hello world!" on the position 10 inside the page 2: 
Glcd Write Text ("Hello world!", 10, 2, 1); 



Glcdjmage 



Prototype 


void Glcd Image (code const unsigned short * image); 


Returns 


Nothing. 


Description 


Displays bitmap on GLCD. 

Parameters: 

- image: image to be displayed. Bitmap array must be located in code memory. 

Use the mikroC PRO for PIC integrated Glcd Bitmap Editor to convert image to 
a constant array suitable for displaying on Glcd. 


Requires 


Glcd needs to be initialized, see Glcdlnit routine. 


Example 


// Draw image my image on Glcd 
Glcd Image (my image) ; 
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Library Example 

The following example demonstrates routines of the Glcd library: initialization, 
clear(pattern fill), image displaying, drawing lines, circles, boxes and rectangles, text 
displaying and handling. 

//Declarations 

const code char truck_bmp[ 1024] ; 

// end _ 

declarations 

// Glcd module connections 
char GLCD_DataPort at PORTD; 

sbit GLCD_CS1 at RBOJoit; 

sbit GLCD_CS2 at RBlJoit; 

sbit GLCD_RS at RB2_bit; 

sbit GLCD_RW at RB3_bit; 

sbit GLCD_EN at RB4_bit; 

sbit GLCD_RST at RB5_bit; 

sbit GLCD_CSl_Direction at TRISB0_bit; 

sbit GLCD_CS2_Direction at TRISBlJoit; 

sbit GLCD_RS_Direction at TRISB2_bit; 

sbit GLCD_RW_Direction at TRISB3_bit; 

sbit GLCD_EN_Direction at TRISB4_bit; 

sbit GLCD_RST_Direction at TRISB5_bit; 
// End Glcd module connections 



void delay2S (){ 

Delay_ms (2000) ; 
} 

void main ( ) { 

unsigned short ii; 
char *someText; 



// 2 seconds delay function 



#define COMPLETE_EXAMPLE // comment this line to make 
simpler/smaller example 

ANSEL = 0; // Configure AN pins as digital 

ANSELH = 0; 

C10N_bit =0; // Disable comparators 

C20N bit = 0; 



Glcd_Init () ; 
Glcd Fill (0x00) ; 



// Initialize GLCD 
// Clear GLCD 



while (1) { 
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#ifdef COMPLETE_EXAMPLE 
Glcd Image (truck bmp) ; 
delay2S(); delay2S(); 

#endif 

Glcd_Fill(0x00) ; 

Glcd_Box (62, 40, 124, 56, 1); 
Glcd_Rectangle (5, 5, 8 4, 35, 1 ) ; 
Glcd_Line(0, 0, 127, 63, 1) ; 
delay2S () ; 



// Draw image 



// Clear GLCD 

// Draw box 
// Draw rectangle 
// Draw line 



for(ii =5; ii < 60; ii+=5 ){ // Draw horizontal and vertical lines 
Delay_ms (250) ; 
Glcd_V_Line (2, 54, ii, 1 ) ; 
Glcd H Line (2, 120, ii, 1); 



delay2S () ; 

Glcd_Fill(0x00) ; 

#ifdef COMPLETE_EXAMPLE 

Glcd_Set_Font (Character8x7, 8, 
Lib_GLCDFonts . c in Uses folder 
#endif 
Glcd_Write_Text ("mikroE", 1, 7, 2) 

for (ii = 1; ii <= 10; ii++) 

Glcd_Circle (63,32, 3*ii, 1); 
delay2S () ; 

Glcd_Box (12,20, 70,57, 2) ; 
delay2S () ; 

#ifdef COMPLETE_EXAMPLE 
Glcd Fill (OxFF) ; 



// Clear GLCD 
7, 32);// Choose font, see 

// Write string 
// Draw circles 

// Draw box 

// Fill GLCD 



Glcd_Set_Font (Character8x7, 8, 7, 32);// Change font 
someText = "8x7 Font"; 

Glcd_Write_Text (someText, 5, 0, 2); // Write string 
delay2S () ; 

Glcd_Set_Font (System3x5, 3, 5, 32); // Change font 
someText = "3X5 CAPITALS ONLY"; 

Glcd_Write_Text (someText, 60, 2, 2); // Write string 
delay2S () ; 



Glcd_Set_Font (font5x7, 5, 7, 32) 
someText = "5x7 Font"; 



// Change font 
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Glcd_Write_Text (someText, 5, 4, 2) 
delay2S () ; 



// Write string 



Glcd_Set_Font (FontSystem5x7_v2, 5, 7, 32); // Change font 
someText = "5x7 Font (v2)"; 

Glcd_Write Text (someText, 5, 6, 2); // Write string 
delay2S () ; 
#endif 



HW Connection 



y axis 



|i. i.l.'; 



I'. 1. 1.;' 



Loft bide 



Right side 127 x ax ' s 
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Glcd HW connection 
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l 2 C LIBRARY 

I^C full master MSSP module is available with a number of PIC MCU models. mikroC PRO for PIC 
provides library which supports the master l L C mode. 

Note: Some MCUs have multiple l L C modules. In order to use the desired l L C library routine, sim- 
ply change the number 1 in the prototype with the appropriate module number, i.e. 

I2Cl_Init (100000); 

Library Routines 

- l2C1_lnit 

- l2C1_Start 

- l2C1_Repeated_Start 

- l2C1_ls_ldle 

- l2C1_Rd 

- l2C1_Wr 

- l2C1_Stop 

I2C1 Init 



Prototype 


void I2C1 Init (unsigned long clock) ; 


Returns 


Nothing. 


Description 


Initializes l L C with desired clock (refer to device data sheet for correct values in 
respect with Fosc). Needs to be called before using other functions of l t C Library. 

You don't need to configure ports manually for using the module; library will take 
care of the initialization. 


Requires 


Library requires MSSP module on PORTB or PORTC. 

Note: Calculation of the I^C clock value is carried out by the compiler, as it would 
produce a relatively large code if performed on the libary level. 
Therefore, compiler needs to know the value of the parameter in the compile time. 
That is why this parameter needs to be a constant, and not a variable. 


Example 


I2C1 Init (100000) ; 
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I2C1 Start 



Prototype 


unsigned short I2C1 Start (void) ; 


Returns 


If there is no error, function returns 0. 


Description 


Determines if I^C bus is free and issues START signal. 


Requires 


I^C must be configured before using this function. See l2C1_lnit. 


Example 


I2Cl_Start () ; 



l2C1_Repeated_Start 



Prototype 


void I2C1 Repeated Start (void) ; 


Returns 


Nothing. 


Description 


Issues repeated START signal. 


Requires 


I^C must be configured before using this function. See l2C1_lnit. 


Example 


I2C1 Repeated Start (); 



I2C1 Is Idle 



Prototype 


unsigned short I2C1 Is Idle (void) ; 


Returns 


Returns 1 if I^C bus is free, otherwise returns 0. 


Description 


Tests if I^C bus is free. 


Requires 


I^C must be configured before using this function. See l2C1_lnit. 


Example 


if (I2C1 Is Idle () ) { . . .} 



I2C1 Rd 



Prototype 


unsigned short I2C1 Rd (unsigned short ack); 


Returns 


Returns one byte from the slave. 


Description 


Reads one byte from the slave, and sends not acknowledge signal if parameter 
ack is 0, otherwise it sends acknowledge. 


Requires 


I^C must be configured before using this function. See l2C1_lnit. 

Also, START signal needs to be issued in order to use this function. See l2C1_Start. 


Example 


Read data and send not acknowledge signal: 

unsigned short take; 
take = I2C1 Rd(0) ; 
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I2C1 Wr 



Prototype 


unsigned short I2C1 Wr (unsigned short data ) ; 


Returns 


Returns if there were no errors. 


Description 


Sends data byte (parameter data) via I^C bus. 


Requires 


I^C must be configured before using this function. See l2C1_lnit. 

Also, START signal needs to be issued in order to use this function. See l2C1_Start. 


Example 


I2C1 Write (0xA3) ; 



l2C1_Stop 



Prototype 


void I2C1 Stop (void); 


Returns 


Nothing. 


Description 


Issues STOP signal. 


Requires 


I^C must be configured before using this function. See l2C1_lnit. 


Example 
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Library Example 

This code demonstrates use of l L C library. PIC MCU is connected (SCL, SDA pins) 
to 24c02 EEPROM. Program sends data to EEPROM (data is written at address 2). 
Then, we read data via l L C from EEPROM and send its value to PORTB, to check 
if the cycle was successful (see the figure below how to interface 24c02 to PIC). 



void main ( ) { 
ANSEL = 0; 
ANSELH = 0; 
PORTB = 0; 
TRISB = 0; 



// Configure AN pins as digital I/O 



// Configure PORTB as output 



I2Cl_Init (100000) ; 
I2Cl_Start () ; 
I2Cl_Wr (0xA2) ; 
I2Cl_Wr (2) ; 
I2Cl_Wr (OxFO) ; 
I2Cl_Stop () ; 



// initialize I2C communication 

// issue I2C start signal 

// send byte via I2C (device address + W) 

// send byte (address of EEPROM location) 

// send data (data to be written) 

// issue I2C stop signal 



Delay_100ms () ; 



I2Cl_Start () ; 
I2Cl_Wr (0xA2) ; 
I2Cl_Wr (2) ; 
I2Cl_Repeated_Start () 
I2Cl_Wr (0xA3) ; 
PORTB = I2Cl_Rd(0u) ; 
I2Cl_Stop () ; 



// issue I2C start signal 

// send byte via I2C (device address + W) 

// send byte (data address) 

// issue I2C signal repeated start 

// send byte (device address + R) 

// Read the data (NO acknowledge) 

// issue I2C stop signal 
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HW Connection 




Interfacing 24c02 to PIC via l 2 C 
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KEYPAD LIBRARY 

The mikroC PRO for PIC provides a library for working with 4x4 keypad. The library routines can 
also be used with 4x1 , 4x2, or 4x3 keypad. For connections explanation see schematic at the bot- 
tom of this page. 



External dependencies of Keypad Library 



The following variable must 

be defined in all projects 

using Keypad Library: 


Description: 


Example: 


extern sfr char 

keypadPort ; 


Keypad Port. 


char keypadPort at PORTD; 



Library Routines 

- Keypadlnit 

- KeypadKeyPress 

- KeypadKeyClick 

Keypadjnit 



Prototype 


void Keypad Init (void) ; 


Returns 


Nothing. 


Description 


Initializes port for working with keypad. 




Global variable: 


Requires 


- keypadPort - Keypad port 




must be defined before using this function. 




// Keypad module connections 




char keypadPort at PORTD; 


Example 


// End of keypad module connections 




Keypad Init ( ) ; 
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Key pad_Key_P ress 



Prototype 


char Keypad Key Press (void) ; 


Returns 


The code of a pressed key (1 ..16). 
If no key is pressed, returns 0. 


Description 


Reads the key from keypad when key gets pressed. 


Requires 


Port needs to be initialized for working with the Keypad library, see Keypadjnit. 


Example 


char kp ; 

kp = Keypad Key Press (); 



Key pad_Key_C lick 



Prototype 


char Keypad Key Click (void) ; 


Returns 


The code of a clicked key (1 ..1 6). 
If no key is clicked, returns 0. 


Description 


Call to Keypad Key click is a blocking call: the function waits until some key is 
pressed and released. When released, the function returns 1 to 16, depending on 
the key. If more than one key is pressed simultaneously the function will wait until 
all pressed keys are released. After that the function will return the code of the 
first pressed key. 


Requires 


Port needs to be initialized for working with the Keypad library, see Keypadjnit. 


Example 


char kp ; 

kp = Keypad Key Click (); 
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Library Example 

This is a simple example of using the Keypad Library. It supports keypads with 1..4 
rows and 1..4 columns. The code being returned by Keypad_Key_Click() function is 
in range from 1 ..16. In this example, the code returned is transformed into ASCII 
codes [0..9,A..F] and displayed on LCD. In addition, a small single-byte counter dis- 
plays in the second LCD row number of key presses. 



unsigned short kp, cnt, oldstate 
char txt[ 6] ; 



0; 



// Keypad module connections 

char keypadPort at PORTD; 

// End Keypad module connections 

// LCD module connections 

sbit LCD_RS at RB4_bit; 

sbit LCD_EN at RB5_bit; 

sbit LCD_D4 at RBOJoit; 

sbit LCD_D5 at RBlJoit; 

sbit LCD_D6 at RB2_bit; 

sbit LCD_D7 at RB3_bit; 

sbit LCD_RS_Direction at TRISB4_bit; 

sbit LCD_EN_Direction at TRISB5_bit; 

sbit LCD_D4_Direction at TRISBOJoit; 

sbit LCD_D5_Direction at TRISBlJoit; 

sbit LCD_D6_Direction at TRISB2_bit; 

sbit LCD_D7_Direction at TRISB3_bit; 
// End LCD module connections 



void main ( ) { 
cnt = 0; 
Keypad_Init () ; 
Lcd_Init () ; 
Lcd_Cmd (_LCD_CLEAR) ; 
Lcd_Cmd (_LCD_CURSOR_OFF) ; 
Lcd_Out (1, 1, "1") ; 
Lcd_Out (1, 1, "Key :") ; 
Led Out (2, 1, "Times:") ; 



// Reset counter 

// Initialize Keypad 

// Initialize Led 

// Clear display 

// Cursor off 

// Write message text on Led 



do { 

kp = 0; 



// Reset key code variable 



// Wait for key to be pressed and released 
do 

//kp = Keypad_Key_Press ( ) ; // Store key code in kp variable 
kp = Keypad_Key Click (); // Store key code in kp variable 
while ( ! kp ) ; 
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// Prepare value for output, transform key to it's ASCII value 
switch (kp) { 

//case 10: kp = 42; break; // '* ' // Uncomment this block for 
keypad4x3 

//case 11: kp = 48; break; // '0' 
//case 12: kp = 35; break; // '#' 
//default: kp += 48; 



1: kp = 49; break; // 1 // Uncomment this block for keypad4x4 



case 


2 


kp = 


50; 


break; 


// 


2 


case 


3 


kp = 


51; 


break; 


// 


3 


case 


4 


kp = 


65; 


break; 


// 


A 


case 


5 


kp = 


52; 


break; 


// 


4 


case 


6 


kp = 


53; 


break; 


// 


5 


case 


7 


kp = 


54; 


break; 


// 


6 


case 


8 


kp = 


66; 


break; 


// 


E 


case 


9 


kp = 


55; 


break; 


// 


7 


case 


10 


kp = 


56; 


break; 


// 


8 


case 


11 


kp = 


57; 


break; 


// 


9 


case 


12 


kp = 


67; 


break; 


// 


C 


case 


13 


kp = 


42; 


break; 


// 


* 


case 


14 


kp = 


48; 


break; 


// 





case 


15 


kp = 


35; 


break; 


// 


# 


case 


16 


kp = 


68; 


break; 


// 


D 



if (kp != oldstate) { // Pressed key differs from previous 
cnt = 1; 



oldstate 
} 
else { 

cnt++; 



kp; 



// Pressed key is same as previous 



Lcd_Chr(l, 10, kp); 

if (cnt == 255) { 
cnt = 0; 

Lcd_0ut(2, 10, " 
} 



// Print key ASCII value on Led 
// If counter varialble overflow 



WordToStr (cnt, txt) ; // Transform counter value to string 
Led Out (2, 10, txt); // Display counter value on Led 
while (1); 
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HW Connection 
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LCD LIBRARY 

The mikroC PRO for PIC provides a library for communication with Lcds (with 
HD44780 compliant controllers) through the 4-bit interface. An example of Led con- 
nections is given on the schematic at the bottom of this page. 

For creating a set of custom Led characters use Led Custom Character Tool. 

External dependencies of LCD Library 



The following variables 

must be defined in all 

projects using Led 

Library: 


Description: 


Example: 


extern sfr sbit 

LCD RS: 


Register Select line. 


RB4 bit; 


extern sfr sbit 

LCD EN: 


Enable line. 


RB5 bit; 


extern sfr sbit 

LCD D7; 


Data 7 line. 


RB3 bit; 


extern sfr sbit 

LCD D6; 


Data 6 line. 


RB2 bit; 


extern sfr sbit 

LCD D5; 


Data 5 line. 


RBI bit; 


extern sfr sbit 

LCD D4; 


Data 4 line. 


RBO bit; 


extern sfr sbit 

LCD RS Direction; 


Register Select direction pin. 


at TRISB4 bit; 


extern sfr sbit 

LCD EN Direction; 


Enable direction pin. 


at TRISB5 bit; 


extern sfr sbit 

LCD D7 Direction; 


Data 7 direction pin. 


at TRISB3 bit; 


extern sfr sbit 

LCD D6 Direction; 


Data 6 direction pin. 


at TRISB2 bit; 


extern sfr sbit 

LCD D5 Direction; 


Data 5 direction pin. 


at TRISB1 bit; 


extern sfr sbit 

LCD D4 Direction; 


Data 4 direction pin. 


at TRISBO bit; 
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Library Routines 

- Lcdjnit 

- Lcd_Out 

- Lcd_Out_Cp 

- Lcd_Chr 

- Lcd_Chr_Cp 

- LcdCmd 

Led Init 



Prototype 


void Led Init ( ) ; 


Returns 


Nothing. 


Description 


Initializes LCD module. 




Global variables: 




- lcd D7: Data bit 7 




- lcd D6: Data bit 6 




- lcd D5: Data bit 5 




- lcd D4: Data bit 4 




- lcd rs: Register Select (data/instruction) signal pin 




- lcd en: Enable signal pin 


Requires 


- lcd D7 Direction: Direction of the Data 7 pin 




- lcd D6 Direction: Direction of the Data 6 pin 




- lcd D5 Direction: Direction of the Data 5 pin 




-lcd D4 Direction: Direction of the Data 4 pin 




- lcd rs Direction: Direction of the Register Select pin 




- lcd en Direction: Direction of the Enable signal pin 




must be defined before using this function. 




// Led pinout settings 




sbit LCD RS at RB4 bit; 




sbit LCD EN at RB5 bit; 




sbit LCD D7 at RB3 bit; 




sbit LCD D6 at RB2 bit; 




sbit LCD D5 at RBI bit; 




sbit LCD D4 at RBO bit; 


Example 


// Pin direction 

sbit LCD RS Direction at TRISB4 bit; 




sbit LCD EN Direction at TRISB5 bit; 




sbit LCD D7 Direction at TRISB3 bit; 




sbit LCD D6 Direction at TRISB2 bit; 




sbit LCD D5 Direction at TRISB1 bit; 




sbit LCD D4 Direction at TRISBO bit; 




Lcd Init () ; 
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Led Out 



Prototype 


void Led Out (char row, char column, char *text); 


Returns 


Nothing. 


Description 


Prints text on Led starting from specified position. Both string variables and liter- 
als can be passed as a text. 

Parameters: 

- row: starting position row number 

- column: starting position column number 

- text: text to be written 


Requires 


The Led module needs to be initialized. See Lcdlnit routine. 


Example 


// Write text "Hello!" on Led starting from row 1, column 3: 
Lcd_Out(l, 3, "Hello!"); 



Led Out CP 



Prototype 


void Led Out CP(char *text); 


Returns 


Nothing. 


Description 


Prints text on LCD at current cursor position. Both string variables and literals 
can be passed as a text. 

Parameters: 

- text: text to be written 


Requires 


The Led module needs to be initialized. See Lcdjnit routine. 


Example 


// Write text "Here!" at current cursor position: 
Led Out CP ("Here! ") ; 
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Led Chr 



Prototype 



Returns 



Description 



Requires 



Example 



void Led Chr (char row, char column, char out char); 



Nothing. 



Prints character on LCD at specified position. Both variables and literals can be 
passed as a character. 

Parameters: 

- row: writing position row number 

- column: writing position column number 

- out char: character to be written 



The Led module needs to be initialized. See Led Init routine. 



// Write character "i" at row 2, column 3: 
Led Chr (2, 3, ' i ' ) ; 



Lcd_Chr_Cp 



Prototype 


void Led Chr CP(char out char); 


Returns 


Nothing. 


Description 


Prints character on LCD at current cursor position. Both variables and literals 
can be passed as a character. 

Parameters: 

- out char: character to be written 


Requires 


The Led module needs to be initialized. See Lcdlnit routine. 


Example 


// Write character "e" at current cursor position: 
Led Chr CP ( 'e' ) ; 
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Led Cmd 



Prototype 


void Led Cmd (char out char); 


Returns 


Nothing. 


Description 


Sends command to LCD. 

Parameters: 

- out char: command to be sent 

Note: Predefined constants can be passed to the function, see Available LCD 
Commands. 


Requires 


The LCD module needs to be initialized. See Lcdlnit table. 


Example 


// Clear Led display: 
Led Cmd( LCD CLEAR); 



Available LCD Commands 



Led Command 


Purpose 


LCD FIRST ROW 


Move cursor to the 1st row 


LCD SECOND ROW 


Move cursor to the 2nd row 


LCD THIRD ROW 


Move cursor to the 3rd row 


LCD FOURTH ROW 


Move cursor to the 4th row 


LCD CLEAR 


Clear display 


LCD RETURN HOME 


Return cursor to home position, returns a shifted display to its original 
position. Display data RAM is unaffected. 


LCD CURSOR OFF 


Turn off cursor 


LCD UNDERLINE ON 


Underline cursor on 


LCD BLINK CURSOR ON 


Blink cursor on 


LCD MOVE CURSOR LEFT 


Move cursor left without changing display data RAM 


LCD MOVE CURSOR RIGHT 


Move cursor right without changing display data RAM 


LCD TURN ON 


Turn LCD display on 


LCD TURN OFF 


Turn LCD display off 


LCD SHIFT LEFT 


Shift display left without changing display data RAM 


LCD SHIFT RIGHT 


Shift display right without changing display data RAM 
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Library Example 

The following code demonstrates usage of the Led Library routines: 

// LCD module connections 

sbit LCD_RS at RB4_bit; 

sbit LCD_EN at RB5_bit; 

sbit LCD_D4 at RBOJoit; 

sbit LCD_D5 at RBl_bit; 

sbit LCD_D6 at RB2_bit; 

sbit LCD D7 at RB3 bit; 



sbit LCD_RS_Direction at TRISB4_bit; 

sbit LCD_EN_Direction at TRISB5_bit; 

sbit LCD_D4_Direction at TRISBOJoit; 

sbit LCD_D5_Direction at TRISBlJoit; 

sbit LCD_D6_Direction at TRISB2_bit; 

sbit LCD_D7_Direction at TRISB3_bit; 
// End LCD module connections 



char txtl[ 

char txt2[ 

char txt3[ 

char txt4[ 

char i ; 



"mikroElektronika" ; 
"EasyPIC5"; 
"Lcd4bit"; 
"example" ; 



void Move_Delay() { 

Delayjns (500) ; 
} 



// Loop variable 

// Function used for text moving 

// You can change the moving speed here 



void main ( ) { 
TRISB = 0; 
PORTB = OxFF; 
TRISB = Oxff; 
ANSEL = 0; 
ANSELH = 0; 
Led Init() 



// Configure AN pins as digital I/O 
// Initialize LCD 



Lcd_Cmd (_LCD_CLEAR) ; 
Lcd_Cmd (_LCD_CURSOR_OFF) 
Led Out (1, 6,txt3) ; 



// Clear display 

// Cursor off 

// Write text in first row 



LcdjDut (2, 6,txt4) ; 
Delayjns (2000) ; 
Lcd_Cmd (_LCD_CLEAR) ; 

Lcd_Out (l,l,txtl) ; 
Led Out (2,5, txt2) ; 



// Write text in second row 

// Clear display 

// Write text in first row 

// Write text in second row 
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Delay_ms (2000) ; 

// Moving text 

for(i=0; i<4; i++) { // Move text to the right 4 times 

Lcd_Cmd(_LCD_SHIFT_RIGHT) ; 

Move_Delay ( ) ; 
} 

while (1) { // Endless loop 

for(i=0; i<8; i++) { // Move text to the left 7 times 

Lcd_Cmd (_LCD_SHIFT_LEFT) ; 
Move_Delay ( ) ; 
} 

for(i=0; i<8; i++) { // Move text to the right 7 times 

Lcd_Cmd (_LCD_SHIFT_RIGHT) ; 
Move_Delay ( ) ; 
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HW connection 




LCD HW connection 
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MANCHESTER CODE LIBRARY 



The mikroC PRO for PIC provides a library for handling Manchester coded signals. 
The Manchester code is a code in which data and clock signals are combined to 
form a single self-synchronizing data stream; each encoded bit contains a transition 
at the midpoint of a bit period, the direction of transition determines whether the bit 
is or 1 ; the second half is the true bit value and the first half is the complement of 
the true bit value (as shown in the figure below). 

Manchester RF r Send_Byte formal 



St1 


St2 


Ctr 


B7 


B6 


B5 


B4 


B3 


B2 


B1 


BO 



2ms 



Bi- phase ceding 

M N 

1 

Example of transmission 



kN 1 ! 



110 10 11 



Notes: The Manchester receive routines are blocking calls (Man Receive init 
and Man synchro). This means that MCU will wait until the task has been per- 
formed (e.g. byte is received, synchronization achieved, etc). 

Note: Manchester code library implements time-based activities, so interrupts need 
to be disabled when using it. 

External dependencies of Manchester Code Library 



The following variables 
must be defined in all proj- 
ects using Manchester 
Code Library: 


Description: 


Example: 


extern sfr sbit MAN- 
RXPIN; 


Receive line. 


RC0 bit; 


extern sfr sbit MAN- 
TXPIN; 


Transmit line. 


RC1 bit; 


extern sfr sbit MAN- 
RXPIN Direction; 


Direction of the Receive pin. 


at TRISC0 bit; 


extern sfr sbit MAN- 
TXPIN Direction; 


Direction of the Transmit pin. 


at TRISC1 bit; 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 359 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



Library Routines 

- Man_Receive_lnit 

- Man_Receive 

- Man_Send_lnit 

- Man_Send 

- Man_Synchro 

- Man_Break 

The following routines are for the internal use by compiler only: 

- ManchesterJD 

- ManchesteM 

- Manchester_Out 

Man Receive Init 



Prototype 


unsigned int Man Receive Init(); 


Returns 


- o - if initialization and synchronization were successful. 

- i - upon unsuccessful synchronization. 

- 255 - upon user abort. 


Description 


The function configures Receiver pin and performs synchronization procedure in 
order to retrieve baud rate out of the incoming signal. 

Note: In case of multiple persistent errors on reception, the user should call this 
routine once again or Man_Synchro routine to enable synchronization. 


Requires 


Global variables: 

manrxpin: Receive line 

manrxpin Direction: Direction of the receive pin 

must be defined before using this function. 


Example 


// Initialize Receiver 

sbit MANRXPIN at RCO bit; 

sbit MANRXPIN Direction at TRISCO bit; 

Man Receive Init(); 
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Man Receive 



Prototype 


unsigned char Man Receive (unsigned char *error); 


Returns 


A byte read from the incoming signal. 


Description 


The function extracts one byte from incoming signal. 

Parameters: 

- error: error flag. If signal format does not match the expected, the error flag 
will be set to non-zero. 


Requires 


To use this function, the user must prepare the MCU for receiving. See 
Man_Receive_lnit. 


Example 


unsigned char data = 0, error = ; 

data = Man Receive ( Serror) ; 
if (error) 

{ /* error handling */ } 



Man Send Init 



Prototype 


void Man Send Init(); 


Returns 


Nothing. 


Description 


The function configures Transmitter pin. 


Requires 


Global variables: 

mantxpin: Transmit line 

mantxpin Direction: Direction of the transmit pin 

must be defined before using this function. 


Example 


// Initialize Transmitter: 

sbit MANTXPIN at RC1 bit; 

sbit MANTXPIN Direction at TRISC1 bit; 

Man Send Init () ; 
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Man Send 



Prototype 


void Man Send (unsigned char tr data); 


Returns 


Nothing. 


Description 


Sends one byte. 

Parameters: 

- tr data : data to be sent 

Note: Baud rate used is 500 bps. 


Requires 


To use this function, the user must prepare the MCU for sending. See 
Man_Send_lnit. 


Example 


unsigned char msg; 
Man Send (msg) ; 



Man_Synchro 



Prototype 


unsigned char Man Synchro)); 


Returns 


- 255 - if synchronization was not successful. 

- Half of the manchester bit length, given in multiples of 10us - upon suc- 
cessful synchronization. 


Description 


Measures half of the manchester bit length with 10us resolution. 


Requires 


To use this function, you must first prepare the MCU for receiving. See 
Man_Receive_lnit. 


Example 


unsigned int man half bit len; 
man half bit len = Man Synchro (); 
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Man Break 



Prototype 



Returns 



Description 



Requires 



Example 



void Man Break (); 



Nothing. 



Man_Receive is blocking routine and it can block the program flow. Call this 
routine from interrupt to unblock the program execution. This mechanism is sim- 
ilar to WDT 

Note: Interrupts should be disabled before using Manchester routines again 
(see note at the top of this page). 



Nothing. 



char datal, error, counter = 0; 
void interrupt { 

if (INTCON.T0IF) { 

if (counter >= 20) { 

Man_Break () ; 

counter = ; 
} 
else 

counter++ ; 



// reset counter 



// increment counter 
INTCON.T0IF = 0; // Clear TimerO overflow interrupt flag 



// TMRO prescaler set to 1:32 



void main ( ) { 

OPTION_REG = 0x0 4; 

Man Receive Init(); 



// try Man^Receive with blocking prevention mechanism 
INTCON.GIE =1; // Global interrupt enable 

INTCON.T0IE = 1; // Enable TimerO overflow 

interrupt 

datal = Man Receive ( Serror) ; 

INTCON.GIE =0; // Global interrupt disable 
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Library Example 

The following code is code for the Manchester receiver, it shows how to use the 
Manchester Library for receiving data: 

// LCD module connections 

sbit LCD_RS at RB4_bit; 

sbit LCD_EN at RB5_bit; 

sbit LCD_D4 at RBOJoit; 

sbit LCD_D5 at RBlJoit; 

sbit LCD_D6 at RB2_bit; 

sbit LCD_D7 at RB3_bit; 

sbit LCD_RS_Direction at TRISB4_bit; 

sbit LCD_EN_Direction at TRISB5_bit; 

sbit LCD_D4_Direction at TRISBOJoit; 

sbit LCD_D5_Direction at TRISBlJoit; 

sbit LCD_D6_Direction at TRISB2_bit; 

sbit LCD_D7_Direction at TRISB3_bit; 
// End LCD module connections 



// Manchester module connections 

sbit MANRXPIN at RCOJoit; 

sbit MANRXPIN_Direction at TRISCOJoit; 

sbit MANTXPIN at RClJoit; 

sbit MANTXPIN_Direction at TRISClJoit; 

// End Manchester module connections 



char error, ErrorCount, temp; 



void main ( ) { 

ErrorCount = ; 
ANSEL = ; 
ANSELH = 0; 
TRISC.F5 = 0; 
Lcd_Init () ; 
Lcd_Cmd (_LCD_CLEAR) 

Man Receive Init(); 

while (1) { 



// Configure AN pins as digital I/O 

// Initialize LCD 

// Clear LCD display 

// Initialize Receiver 

// Endless loop 



Led Cmd( LCD FIRST ROW) ; 



// Move cursor to the 1st row 



while (1) { // Wait for the "start" byte 

temp = Man_Receive ( Serror ) ; // Attempt byte receive 
if (temp == OxOB)// "Start" byte, see Transmitter example 
break; // We got the starting sequence 
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if (error) 
break; 



// Exit so we do not loop forever 



do 

{ 

temp = Man Receive (Serror) ; // Attempt byte receive 
if (error) { // If error occured 

Lcd_Chr_CP ( '? ' ) ; // Write question mark on LCD 

ErrorCount++; // Update error counter 

if (ErrorCount > 20) { // In case of multiple errors 

temp = Man Synchro(); // Try to synchronize again 
//Man Receive Init(); // Alternative, try to Initialize 
Receiver again 

ErrorCount =0; // Reset error counter 



else { // No error occured 

if (temp != OxOE) // If "End" byte was receivedfsee 
Transmitter example) 

Lcd_Chr_CP (temp) ; // do not write received byte on LCD 



Delay_ms (25) 



1 



while (temp != OxOE);// If "End" byte was received exit do loop 
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The following code is code for the Manchester transmitter, it shows how to use the 
Manchester Library for transmitting data: 

// Manchester module connections 

sbit MANRXPIN at RCOJoit; 

sbit MANRXPIN_Direction at TRISCOJoit; 

sbit MANTXPIN at RClJoit; 

sbit MANTXPIN_Direction at TRISClJoit; 

// End Manchester module connections 

char index, character; 

char sl[ ] = "mikroElektronika" ; 

void main ( ) { 



Man Send Init () ; 



// Initialize transmitter 



while (1) { 

Man_Send (OxOB) ; 
Delay_ms (100) ; 



// Endless loop 

// Send "start" byte 

// Wait for a while 



character = sl[ 0] ; 

index = ; 

while (character) { 

Man Send (character ) ; 

Delay_ms (90) ; 

index++; 

character = sl[ index] 



// Take first char from string 

// Initialize index variable 

// String ends with zero 

// Send character 

// Wait for a while 

// Increment index variable 

// Take next char from string 



Man_Send(0x0E) ; 
Delayjns (1000) ; 



// Send "end" byte 
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Connection Example 



Transmitter RF 
module 



Antenna 




OSCLLJCTtK VCC 0—\_ VOC 
||— [j(3ND 

CLK1N 




Simple Transmitter connection 



Receiver RF 
module 



Antenna 




Simple Receiver connection 
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MULTI MEDIA CARD LIBRARY 

The Multi Media Card (MMC) is a flash memory card standard. MMC cards are cur- 
rently available in sizes up to and including 1 GB, and are used in cell phones, mp3 
players, digital cameras, and PDA's. 

mikroC PRO for PIC provides a library for accessing data on Multi Media Card via 
SPI communication. This library also supports SD(Secure Digital) memory cards. 

Secure Digital Card 

Secure Digital (SD) is a flash memory card standard, based on the older Multi Media 
Card (MMC) format. 

SD cards are currently available in sizes of up to and including 2 GB, and are used 
in cell phones, mp3 players, digital cameras, and PDAs. 

Notes: 

- Library works with PIC18 family only; 

- The library uses the SPI module for communication. User must initialize 
SPI module before using the SPI Graphic Led Library. 

- For MCUs with two SPI modules it is possible to initialize both of them and 
then switch by using the spiSetActive o routine. 

- Routines for file handling can be used only with FAT16 file system. 

- Library functions create and read files from the root directory only; 

- Library functions populate both FAT1 and FAT2 tables when writing to files, 
but the file data is being read from the FAT1 table only; i.e. there is no 
recovery if FAT1 table is corrupted. 

Note: The SPI module has to be initialized through spuinit Advanced routine 
with the following parameters: 

- SPI Master 

- 8bit mode 

- primary prescaler 16 

- Slave Select disabled 

- data sampled in the middle of data output time 

- clock idle low 

- Serial output data changes on transition from idle clock state to active 
clock state 

SPIl_Init_Advanced (_SPI_MASTER_OSC_DIV16, _SPI_DATA_SAMPLE_MIDDLE, 

_spi_clk_idle_low, _spi_low_2_high ) ; must be called before initializing 
Mmc Init. 
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Note: Once the MMC/SD card is initialized, the user can reinitialize SPI at higher 
speed. See the Mmcjnit and Mmc_Fat_lnit routines. 



External dependencies of MMC Library 



The following variable must 

be defined in all projects 

using MMC library: 


Description: 


Example: 


extern sfr sbit 

Mmc Chip Select; 


Chip select pin. 


sbit Mmc_Chip_Select at 
RC2 bit 


extern sfr sbit 

Mmc Chip Select Direction; 


Direction of the 
chip select pin. 


sbit 

Mmc Chip Select Direction 
at TRISC2__bit; 



Library Routines 

- Mmcjnit 

- MmcReadSector 

- Mmc_Write_Sector 

- MmcReadCid 

- MmcReadCsd 

Routines for file handling: 



Mmc 


Fat Init 


Mmc 


Fat QuickFormat 


Mmc 


Fat Assign 


Mmc 


Fat Reset 


Mmc 


Fat Read 


Mmc 


Fat Rewrite 


Mmc 


FatAppend 


Mmc 


Fat Delete 


Mmc 


Fat Write 


Mmc 


Fat Set File Date 


Mmc 


Fat Get File Date 


Mmc 


Fat Get File Size 


Mmc 


Fat_Get_Swap_File 
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Mmc Init 



Prototype 


unsigned char Mmc Init(); 


Returns 


j - if MMC/SD card was detected and successfuly initialized 
- 1 - otherwise 


Description 


Initializes hardware SPI communication; The function returns 1 if MMC card is 

present and successfuly initialized, otherwise returns 0. 

Mmcjnit needs to be called before using other functions of this library. 


Requires 


Global variables: 

-Mmc chip select: Chip Select line 

-Mmc chip select Direction: Direction of the Chip Select pin 

must be defined before using this function. 


Example 


// MMC module connections 

sfr sbit Mmc Chip Select at RC2 bit; 

sfr sbit Mmc Chip Select Direction at TRISC2 bit; 

// MMC module connections 

SPI1 Init () ; 

error = Mmc InitO; // Init with CS line at RC2 bit 



Mmc Read Sector 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned char Mmc_Read_Sector (unsigned long sector, char* dbuf f ) ; 



Returns if read was successful, or 1 if an error occurred. 



Function reads one sector (512 bytes) from MMC card at sector address sector. 
Read data is stored in the array data. Function returns if read was successful, 
or 1 if an error occurred. 



Library needs to be initialized, see Mmcjnit. 



error = Mmc Read Sector (sector, data) 
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Mmc Write Sector 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned char Mmc_Write_Sector (unsigned long sector, char *dbuff) ; 



Returns if write was successful; returns 1 if there was an error in sending 
write command; returns 2 if there was an error in writing. 



Function writes 512 bytes of data to MMC card at sector address sector. 
Function returns if write was successful, or 1 if there was an error in sending 
write command, or 2 if there was an error in writing. 



Library needs to be initialized, see Mmcjnit. 



error := Mmc Write Sector (sector , data) 



Mmc Read Cid 



Prototype 



unsigned char Mmc_Read_Cid (char * data_f or_registers) 



Returns 



Returns if read was successful, or 1 if an error occurred. 



Description 



Function reads CID register and returns 16 bytes of content into 



data for reqisters. 



Requires 



Library needs to be initialized, see Mmcjnit. 



Example 



error = Mmc Read Cid(data); 



Mmc Read Csd 



Prototype 



unsigned char Mmc_Read_Csd (char * data_f or_registers) 



Returns 



Returns if read was successful, or 1 if an error occurred. 



Description 



Function reads CSD register and returns 16 bytes of content into 

data for registers. 



Requires 



Library needs to be initialized, see Mmcjnit. 



Example 



error = Mmc Read Csd(data); 
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Mmc Fat Init 



Prototype 


unsigned short Mmc Fat Init(); 


Returns 


o - if MMC/SD card was detected and successfuly initialized 

- 1 - if FAT16 boot sector was not found 

- 255 - if MMC/SD card was not detected 


Description 


Initializes MMC/SD card, reads MMC/SD FAT16 boot sector and extracts neces- 
sary data needed by the library. 
Note: MMC/SD card has to be formatted to FAT16 file system. 


Requires 


Global variables: 

-Mmc chip select: Chip Select line 

-Mmc chip select Direction: Direction of the Chip Select pin 

must be defined before using this function. 

The appropriate hardware SPI module must be previously initialized. See the 
SPMJnit, SPI1Jnit_Advanced routines. 


Example 


// MMC module connections 

sfr sbit Mmc Chip Select at RC2 bit; 

sfr sbit Mmc Chip Select Direction at TRISC2 bit; 

// MMC module connections 

// Initialize SPI1 module and set pointer (s) to SPI1 functions 
SPI1 Init Advanced (MASTER OSC DIV64, DATA SAMPLE MIDDLE, 
CLK IDLE LOW, LOW 2 HIGH); 

// use fatl6 quick format instead of init routine if a formatting 

is needed 

if ( !Mmc Fat Init () ) { 

// reinitialize SPI1 at higher speed 

SPI1 Init Advanced (MASTER OSC DIV4 , DATA SAMPLE MIDDLE, 

CLK IDLE LOW, LOW 2 HIGH); 

} 
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Mmc Fat QuickFormat 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned char Mmc_Fat_QuickFormat (char * mmc_fat_label) ; 



- o - if MMC/SD card was detected and successfuly initialized 

- 1 - if FAT16 format was unseccessful 

- 255 - if MMC/SD card was not detected 



Formats to FAT16 and initializes MMC/SD card. 

Parameters: 

- mmcf atiabei: volume label (11 characters in length). If less than 11 charac- 
ters are provided, the label will be padded with spaces. If null string is passed 
volume will not be labeled 

Note: This routine can be used instead or in conjunction with Mmc_Fat_lnit rou- 
tine. 

Note: If MMC/SD card already contains a valid boot sector, it will remain 
unchanged (except volume label field) and only FAT and ROOT tables will be 
erased. Also, the new volume label will be set. 



The appropriate hardware SPI module must be previously initialized. 



// Initialize SPI1 module and set pointer (s) to SPI1 functions 
SPIl_Init_Advanced (MASTER_OSC_DIV64, DATA_SAMPLE_MIDDLE, 
CLK_IDLE_LOW, L0W_2_HIGH); 

// Format and initialize MMC/SD card and MMC_FAT16 library glob- 

als 

if ( !Mmc_Fat_QuickFormat (&mmc_fat_label) ) { 

// Reinitialize the SPI module at higher speed (change primary 

prescaler) . 

SPIl_Init_Advanced(MASTER_0SC_DIV4, DATA_SAMPLE_MIDDLE, 

CLK IDLE LOW, LOW 2 HIGH); 
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Mmc_Fat_Assign 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned short Mmc_Fat_As sign (char * filename, char file_cre_attr) 



: - if file already exists or file does not exist but new file is created. 
- if file does not exist and no new file is created. 



Assigns file for file operations (read, write, delete...). All subsequent file opera- 
tions will be applied over the assigned file. 

Parameters: 

- filename: name of the file that should be assigned for file operations. File name 
should be in DOS 8.3 (file_name. extension) format. The file name and extension will 
be automatically padded with spaces by the library if they have less than length 
required (i.e. "mikro.tx" -> "mikro .tx "), so the user does no have to take care of that. 
The file name and extension are case insensitive. The library will convert them to 
proper case automatically, so the user does not have to take care of that. Also, in 
order to keep backward compatibility with first version of this library, file names can 
be entered as UPPERCASE string of 11 bytes in length with no dot character 
between file name and extension (i.e. "MIKROELETXT" -> MIKROELE.TXT). In this 
case last 3 characters of the string are considered to be file extension. 

- file ere attr: file creation and attributs flags. Each bit corresponds to 
appropriate file attribut: 



Bit 


Mask 


Description 





0x01 


Read Only 


1 


0x02 


Hidden 


2 


0x04 


System 


3 


0x08 


Volume Label 


4 


0x10 


Subdirectory 


5 


0x20 


Archive 


6 


0x40 


Device (internal use only, never found on disk) 


7 


0x80 


File creation flag. If file does not exist and this flag is set, 
new file with specified name will be created. 



Note: Long File Names (LFN) are not supported. 



MMC/SD card and MMC library must be initialized for file operations. See 
Mmc Fat Init. 



//Create file with archive attribut if it does not already exists 
Mmc_Fat_Assign ( 'MIKROELE.TXT' , OxAO) ; 
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Mmc_Fat_Reset 






Prototype 


void Mmc Fat Reset (unsigned long * size) ; 






Returns 


Nothing. 






Description 


Procedure resets the file pointer (moves it to the start of the file) of the assigned 

file, so that the file can be read. 

Parameter size stores the size of the assigned file, in bytes. 






Requires 


The file must be assigned, see Mmc_Fat_Assign. 






Example 


Mmc Fat Reset ( size ) ; 






Mmc_Fat_Rewrite 






Prototype 


void Mmc Fat Rewrite (); 






Returns 


Nothing. 






Description 


Procedure resets the file pointer and clears the assigned file, so that new data 
can be written into the file. 






Requires 


The file must be assigned, see Mmc_Fat_Assign. 






Example 


Mmc Fat Rewrite; 






Mmc_Fat_Append 






Prototype 


void Mmc Fat Append ( ) ; 






Returns 


Nothing. 






Description 


The procedure moves the file pointer to the end of the assigned file, so that 
data can be appended to the file. 






Requires 


The file must be assigned, see Mmc_Fat_Assign. 






Example 


Mmc Fat Append; 
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Mmc_Fat_Read 






Prototype 


void Mmc Fat Read (unsigned short *bdata) ; 






Returns 


Nothing. 






Description 


Procedure reads the byte at which the file pointer points to and stores data into 
parameter data. The file pointer automatically increments with each call of 

Mmc Fat Read. 






Requires 


The file must be assigned, see Mmc_Fat_Assign. Also, file pointer must be ini- 
tialized; see MmcFatReset. 






Example 


Mmc Fat Read(mydata) ; 






Mmc_Fat_Delete 






Prototype 


void Mmc Fat Delete (); 






Returns 


Nothing. 






Description 


Deletes currently assigned file from MMC/SD card. 






Requires 


MMC/SD card and MMC library must be initialized for file operations. See 

Mmc_Fat_lnit. 

The file must be previously assigned. See Mmc_Fat_Assign. 






Example 


// delete current file 
Mmc Fat Delete () ; 






Mmc_Fat_Write 






Prototype 


void Mmc Fat Write (char * fdata, unsigned data len) ; 






Returns 


Nothing. 






Description 


Procedure writes a chunk of bytes (fdata) to the currently assigned file, at the 
position of the file pointer. 






Requires 


The file must be assigned, see Mmc_Fat_Assign. Also, file pointer must be ini- 
tialized; see Mmc_Fat_Append or Mmc_Fat_Rewrite. 






Example 


Mmc Fat Write (txt, 255) ; 

Mmc Fat Write ('Hello world ', 255) ; 
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Mmc Fat Set File Date 



Prototype 


void Mmc Fat Set File Date (unsigned int year, unsigned short 
month, unsigned short day, unsigned short hours, unsigned short 
mins, unsigned short seconds); 


Returns 


Nothing. 


Description 


Writes system timestamp to a file. Use this routine before each writing to file; 
otherwise, the file will be appended an unknown timestamp. 


Requires 


The file must be assigned, see Mmc_Fat_Assign. Also, file pointer must be ini- 
tialized; see Mmc_Fat_Reset. 


Example 


// April 1st 2005, 18:07:00 

Mmc Fat Set File Date (2005, 4, 1, 18, 7, 0); 



Mmc Fat Get File Date 



Prototype 


void Mmc Fat Get File Date (unsigned int *year, unsigned short *month, 
unsigned short *day, unsigned short * hours, unsigned short *mins) ; 


Returns 


Nothing. 


Description 


Retrieves date and time for the currently selected file. Seconds are not being 
retrieved since they are written in 2-sec increments. 


Requires 


The file must be assigned, see Mmc_Fat_Assign. 


Example 


// get Date/time of file 

unsigned yr; 

char mnth, dat, hrs, rains; 

file Name = "MYFILEABTXT" ; 
Mmc Fat Assign (file Name); 
Mmc Fat Get File Date(yr, mnth, dat, hrs, mins); 



Mmc Fat Get File Size 



Prototype 


unsigned long Mmc Fat Get File Size(); 


Returns 


This function returns size of active file (in bytes). 


Description 


Retrieves size for currently selected file. 


Requires 


The file must be assigned, see Mmc_Fat_Assign. 


Example 


// get Date/time of file 
unsigned yr; 

char mnth, dat, hrs, mins; 

file name = "MYFILEXXTXT" ; 
Mmc Fat Assign (file name); 
mmc size = Mmc Fat Get File Size; 
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Mmc_Fat_Get_Swap_File 



Prototype 



Returns 



Description 



unsigned long Mmc_Fat_Get_Swap_File (unsigned long sectors_cnt, 

filename, char file attr) ; 



char* 



Number of the start sector for the newly created swap file, if there was enough 
free space on the MMC/SD card to create file of required size. 
o - otherwise. 



This function is used to create a swap file of predefined name and size on the 
MMC/SD media. If a file with specified name already exists on the media, search 
for consecutive sectors will ignore sectors occupied by this file. Therefore, it is 
recomended to erase such file if it exists before calling this function. If it is not 
erased and there is still enough space for new swap file, this function will delete 
it after allocating new memory space for new swap file. 

The purpose of the swap file is to make reading and writing to MMC/SD media as 
fast as possible, by using the Mmc_Read_Sector() and Mmc_Write_Sector() 
functions directly, without potentially damaging the FAT system. Swap file can be 
considered as a "window" on the media where user can freely write/read the data. 
It's main purpose in mikroC's library is to be used for fast data acquisition; when 
the time-critical acquisition has finished, the data can be re-written into a "normal" 
file, and formatted in the most suitable way. 

Parameters: 

- sectors cnt: number of consecutive sectors that user wants the swap file to 
have. 

- filename: name of the file that should be assigned for file operations. File name 
should be in DOS 8.3 (file_name. extension) format. The file name and extension 
will be automatically padded with spaces by the library if they have less than 
length required (i.e. "mikro.tx" -> "mikro .tx "), so the user does no have to take 
care of that. The file name and extension are case insensitive. The library will con- 
vert them to proper case automatically, so the user does not have to take care of 
that. 

Also, in order to keep backward compatibility with first version of this library, file 
names can be entered as UPPERCASE string of 11 bytes in length with no dot 
character between file name and extension (i.e. "MIKROELETXT" -> 
MIKROELE.TXT). In this case last 3 characters of the string are considered to be 
file extension. 
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Description 



Requires 



Example 



- f He attr: file creation and attributs flags. Each bit corresponds to appropri- 
ate file attribut: 



Bit 


Mask 


Description 





0x01 


Read Only 


1 


0x02 


Hidden 


2 


0x04 


System 


3 


0x08 


Volume Label 


4 


0x10 


Subdirectory 


5 


0x20 


Archive 


6 


0x40 


Device (internal use only, never found on disk) 


7 


0x80 


Not used 



Note: Long File Names (LFN) are not supported. 



MMC/SD card and MMC library must be initialized for file operations. See 
Mmc Fat Init. 



Tries to create a swap file, whose size will be at 



// 

least 100 sectors. 

//If it succeeds, it sends the No. of start sector over UART 

void M_Create_Swap_File (){ 

size = Mmc_Fat_Get_Swap_File(100) ; 
if (size <> 0) { 

UART_Write (OxAA) ; 

UART_Write (Lo (size) ) ; 

UART_Write (Hi (size) ) ; 

UART_Write (Higher (size) ) ; 

UART_Write (Highest (size) ) ; 

UART Write (OxAA) ; 
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Library Example 

The following example demonstrates MMC library test. Upon flashing, insert a 
MMC/SD card into the module, when you should receive the "Init-OK" message. 
Then, you can experiment with MMC read and write functions, and observe the 
results through the Usart Terminal. 

// MMC module connections 

sbit Mmc_Chip_Select at RC2_bit; 

sbit Mmc_Chip_Select_Direction at TRISC2_bit; 
// eof MMC module connections 

// Variables for MMC routines 

unsigned char SectorData[ 512] ; // Buffer for MMC sector reading/writing 

unsigned char data_for_registers[ 16] ;// buffer for CID and CSD registers 

// UART1 write text and new line (carriage return + line feed) 
void UARTl_Write_Line (char *uart_text) { 

UARTl_Write_Text (uart_text) ; 

UARTl_Write (13) ; 

UARTl_Write (10) ; 
} 



// Display byte in hex 
void PrintHex (unsigned char i) { 
unsigned char hi,lo; 



hi = i & OxFO; 

hi = hi >> 4; 

hi = hi + ' 0' ; 

if (hi>'9') hi=hi+7; 

lo = (i & OxOF) + '0 

if (lo>'9') lo=lo+7; 



// High nibble 



// Low nibble 



UARTl_Write (hi) ; 
UART1 Write (lo) ; 



void main ( ) { 



const char 
unsigned int 
char 
bit 



FILL_CHAR = 'm' 
i, SectorNo; 

mmc error; 

data ok; 



ADCON1 |= OxOF; 
CMCON | = 7 ; 



// Configure AN pins as digital 
// Turn off comparators 



// Initialize UART1 module 
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UARTl_Init (19200) ; 
Delayjns (10) ; 

UARTl_Write_Line ("PIC-Started") ; // PIC present report 

// Initialize SPI1 module 

SPIl_Init_Advanced(_SPI_MASTER_OSC_DIV6 4, _SPI_DATA_SAMPLE_MIDDLE , 
_SPI_CLK_IDLE_LOW, _SPI_LOW_2_HIGH) ; 

// initialise a MMC card 
mmc error = Mmc Init(); 
if (mmc error == 0) 

UARTl_Write_Line ("MMC Init-OK"); // If MMC present report 
else 

UARTl_Write_Line ("MMC Init-error" ) ; // If error report 

// Fill MMC buffer with same characters 
for(i=0; i<=511; i++) 

SectorData[ i] = FILL_CHAR; 

// Write sector 

mmc error = Mmc Write Sector (SectorNo, SectorData) ; 

if (mmc error == 0) 

UARTl_Write_Line ("Write-OK") ; 
else // if there are errors 

UARTl_Write_Line ("Write-Error" ) ; 

// Reading of CID register 

mmc error = Mmc_Read Cid(data for registers); 

if (mmc error == 0) { 

UARTl_Write_Text ("CID : "); 

for(i=0; i<=15; i++) 

PrintHex (data for registers! i] ) ; 

UARTl_Write_Line ("") ; 
} 
else 

UARTl_Write_Line ( "CID-error" ) ; 

// Reading of CSD register 

mmc error = Mmc_Read_Csd (data for registers); 

if (mmc error == 0) { 

UARTl_Write_Text ("CSD : "); 

for(i=0; i<=15; i++) 

PrintHex (data for registers! i] ) ; 

UARTl_Write_Line ("") ; 
} 
else 

UARTl_Write_Line ("CSD-error" ) ; 

// Read sector 
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mmc error = Mmc_Read_Sector (SectorNo, SectorData) 
if (nunc error == 0) { 

UARTl_Write_Line ("Read-OK") ; 
// Chech data match 
data_ok = 1 ; 
for(i=0; i<=511; i++) { 

UARTl_Write (SectorData[ i] ) ; 
if (SectorData[ i] != FILL_CHAR) { 
data_ok = 0; 
break; 
} 
} 

UARTl_Write_Line ("") ; 
if (data_ok) 

UARTl_Write_Line ( "Content-OK" ) ; 
else 

UART1 Write Line ("Content-Error") ; 



else // if there are errors 

UART1 Write Line ("Read-Error") ; 



// Signal test end 

UART1 Write Line ("Test End.") 
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HW Connection 
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ONEWIRE LIBRARY 

The OneWire library provides routines for communication via the Dallas OneWire 
protocol, for example with DS18x20 digital thermometer. OneWire is a Master/Slave 
protocol, and all communication cabling required is a single wire. OneWire enabled 
devices should have open collector drivers (with single pull-up resistor) on the 
shared data line. 

Slave devices on the OneWire bus can even get their power supply from data line. 
For detailed schematic see device datasheet. 

Some basic characteristics of this protocol are: 

- single master system, 

- low cost, 

- low transfer rates (up to 16 kbps), 

- fairly long distances (up to 300 meters), 

- small data transfer packages. 

Each OneWire device also has a unique 64-bit registration number (8-bit device 
type, 48-bit serial number and 8-bit CRC), so multiple slaves can co-exist on the 
same bus. 

Note that oscillator frequency Fosc needs to be at least 4MHz in order to use the 
routines with Dallas digital thermometers. 

Note: This library implements time-based activities, so interrupts need to be dis- 
abled when using OneWire library. 

Library Routines 

- OwReset 

- OwRead 

- Ow Write 
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Ow_Reset 










Prototype 


unsigned short Ow Reset (unsigned short *port, unsigned 


short pin) ; 






Returns 


if DS1820 is present, and 1 if not present. 






Description 


Issues OneWire reset signal for DS1820. Parameters PORT and 
location of DS 1820. 


pin specify the 






Requires 


Works with Dallas DS1820 temperature sensor only. 






Example 


To reset the DS1820 that is connected to the RA5 pin: 

Ow Reset (&P0RTA, 5) ; 






Ow_Read 










Prototype 


unsigned short Ow Read (unsigned short *port, unsigned 


short pin) ; 






Returns 


Data read from an external device over the OneWire bus. 






Description 


Reads one byte of data via the OneWire bus. 






Requires 


Nothing. 






Example 


unsigned short tmp; 

tmp = Ow Read(&PORTA, 5 ) ; 






Ow_Write 










Prototype 


void Ow Write (unsigned short *port, unsigned short pin, unsigned 
short par) ; 






Returns 


Nothing. 






Description 


Writes one byte of data (argument par) via OneWire bus. 






Requires 


Nothing. 






Example 


Ow Write (&PORTA, 5, OxCC) ; 
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Library Example 

This example reads the temperature using DS18x20 connected to pin PORTA. B5. 
After reset, MCU obtains temperature from the sensor and prints it on the Led. Make 
sure to pull-up PORTA.B5 line and to turn off the PORTA LEDs. 

// LCD module connections 

sbit LCD_RS at RB4_bit; 

sbit LCD_EN at RB5_bit; 

sbit LCD_D4 at RBOJoit; 

sbit LCD_D5 at RBl_bit; 

sbit LCD_D6 at RB2_bit; 

sbit LCD_D7 at RB3_bit; 

sbit LCD_RS_Direction at TRISB4_bit; 

sbit LCD_EN_Direction at TRISB5_bit; 

sbit LCD_D4_Direction at TRISBOJoit; 

sbit LCD_D5_Direction at TRISBlJoit; 

sbit LCD_D6_Direction at TRISB2_bit; 

sbit LCD_D7_Direction at TRISB3_bit; 
// End LCD module connections 

// Set TEMP_RESOLUTION to the corresponding resolution of used 

DS18x20 sensor: 

// 18S20: 9 (default setting; can be 9, 10, 11, or 12) 

// 18B20: 12 

const unsigned short TEMP_RESOLUTION = 9; 

char *text = "00 0.00 00"; 

unsigned temp; 

void Display_Temperature (unsigned int temp2write) { 

const unsigned short RES_SHIFT = TEMP_RESOLUTION - 8; 

char temp whole; 

unsigned int temp fraction; 

// check if temperature is negative 
if (temp2write & 0x8000) { 

text[ 0] = '-'; 

temp2write = ~temp2write + 1; 

} 
// extract temp_whole 
temp_whole = temp2write » RES_SHIFT; 

// convert temp^whole to characters 
if (temp_whole/100) 

text[ 0] = temp_whole/100 + 48; 
else 

text[ 0] = ' ' ; 
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text[ 1] = (temp_whole/10) %10 + 48 
text[ 2] = temp_whole%10 + 4i 



// Extract tens digit 
// Extract ones digit 



// extract temp fraction and convert it to unsigned int 

temp_fraction = temp2write « ( 4-RES_SHIFT) ; 

temp_f raction S= OxOOOF; 

temp fraction *= 625; 

// convert temp fraction to characters 

text[ 4] = temp_fraction/1000 + 48; 

text[ 5] = (temp_fraction/100) %10 + 48 

text[ 6] = (temp_fraction/10) %10 + 48 

text[ 7] = temp fraction%10 + 4! 

// print temperature on LCD 

Led Out (2, 5, text) ; 



// Extract thousands digit 
// Extract hundreds digit 
// Extract tens digit 
// Extract ones digit 



void main ( ) { 

ANSEL = 0; 

ANSELH = 0; 

Lcd_Init () ; 

Lcd_Cmd (_LCD_CLEAR) ; 

Lcd_Cmd (_LCD_CURSOR_OFF) ; 

Lcd_Out(l, 1, " Temperature: "); 

// Print degree character, 'C' for Centigrades 

Led Chr (2 , 13, 223 ) ; // different LCD displays have different char 
code for degree 

// if you see greek alpha letter try typing 178 instead of 223 



// Configure AN pins as digital I/O 

// Initialize LCD 
// Clear LCD 
// Turn cursor off 



Led Chr (2,14, 'C') ; 



// main loop 

do { 

// perform temperature reading 

Ow_Reset (SPORTA, 5) ; 

Ow_Write (SPORTA, 5, OxCC) ; 

Ow_Write (SPORTA, 5, 0x44); 

Delay_us (120) ; 



// Onewire reset signal 
// Issue command SKIP_ROM 
// Issue command CONVERT T 



Ow_Reset (SPORTA, 5) ; 
Ow_Write (SPORTA, 5, OxCC); 
Ow Write (SPORTA, 5, OxBE); 



// Issue command SKIP_ROM 
// Issue command READ SCRATCHPAD 



temp = Ow_Read( SPORTA, 5) ; 

temp = (Ow_Read (SPORTE, 5) « 8) + temp; 

// Format and display result on Led 

Display_Temperature (temp) ; 

Delayjns (500) ; 
while (1); 
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HW Connection 



125°C 



GND 




VCC 



-50°C 



■ll — [ GND J* 



L 

r 
i" 
[ 
r 
[ 

{ RA6 

: 
i" 

L 



o 



RB5 
RB4 
RB3 
RB2 
RBI 
RBO 
VCC 



00 

^1 



K- 



SS^iliSUIiiii 



ND ]— 1|" 



1 4444« < 4 14 

a ■ j uj ca j iu o Euetwtt 



i >™'i - i!~ ':::•! *:::! '..■ ►„■! i f ■ 



Example of DS1820 connection 



388 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 7 
Libraries 



PORT EXPANDER LIBRARY 

The mikroC PRO for PIC provides a library for communication with the Microchip's 
Port Expander MCP23S1 7 via SPI interface. Connections of the PIC compliant MCU 
and MCP23S17 is given on the schematic at the bottom of this page. 

Note: Library does not use Port Expander interrupts. 

Note: The appropriate hardware SPI module must be initialized before using any of 

the Port Expander library routines. Refer to SPI Library. 

External dependencies of Port Expander Library 



The following variables 

must be defined in all 

projects using Port 

Expander Library: 


Description: 


Example: 


extern sfr sbit 

SPExpanderRST; 


Reset line. 


at P1.B1; 


extern sfr sbit 

SPExpanderCS; 


Chip Select line. 


at PI. BO; 


extern sfr sbit 

SPExpanderRST Direction; 


Direction of the Reset pin. 


sbit 

SPExpanderRST Direction 
at TRISCO bit; 


extern sfr sbit 

SPExpanderCS Direction; 


Direction of the Chip 
Select pin. 


sbit 

SPExpanderCS Direction 
at TRISC1 bit 



Library Routines 



Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 
Expander 



hit 

ReadByte 

Write_Byte 

ReadPortA 

ReadPortB 

ReadPortAB 

Write_PortA 

Write_PortB 

Write_PortAB 

SetDirectionPortA 

SetDirectionPortB 

SetDirectionPortAB 

Set_PullUpsPortA 

Set_PullUpsPortB 

Set_PullUpsPortAB 
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ExpandeMnit 



Prototype 


void Expander Init (char ModuleAddress ) ; 


Returns 


Nothing. 


Description 


Initializes Port Expander using SPI communication. 
Port Expander module settings: 

- hardware addressing enabled 

- automatic address pointer incrementing disabled (byte mode) 

- BANKO register adressing 

- slew rate enabled 

Parameters: 

- ModuleAddress: Port Expander hardware address, see schematic at the 
bottom of this page 


Requires 


Global variables: 

- sPExpandercs: Chip Select line 

- SPExpanderRST: Reset line 

- SPExpandercs Direction: Direction of the Chip Select pin 

- SPExpanderRST Direction: Direction of the Reset pin 

must be defined before using this function. 

SPI module needs to be initialized. See SPMJnit and SPI1_lnit_Advanced routines. 


Example 


// Port Expander module connections 

sbit SPExpanderRST at RCO bit; 

sbit SPExpanderCS at RC1 bit; 

sbit SPExpanderRST Direction at TRISCO bit; 

sbit SPExpanderCS Direction at TRISC1 bit; 

// End Port Expander module connections 

ANSEL = 0; // Configure AN pins as digital I/O 
ANSELH = 0; 

// If Port Expander Library uses SPI module 

SPI1 InitO; // Initialize SPI module used with 

PortExpander 

Expander Init(O); // Initialize Port Expander 



390 MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 7 
Libraries 



Expander_Read_Byte 



Prototype 



Returns 



Description 



Requires 



Example 



char Expander_Read_Byte (char ModuleAddress, char RegAddress); 



Byte read. 



The function reads byte from Port Expander. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- RegAddress : Port Expander's internal register address 



Port Expander must be initialized. See Expanderjnit. 



// Read a byte from Port Expander's register 
char read_data; 

read data = Expander Read_Byte (0, 1) ; 



Expander_Write_Byte 



Prototype 



void Expander_Write_Byte (char ModuleAddress, char RegAddress, 
char Data) ; 



Returns 



Nothing. 



Description 



Routine writes a byte to Port Expander. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- RegAddress : Port Expander's internal register address 

- Data : data to be written 



Requires 



Port Expander must be initialized. See Expanderjnit. 



Example 



// Write a byte to the Port Expander's register 
Expander_Write_Byte (0,1, $FF) ; 
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Expander_Read_PortA 



Prototype 


char Expander Read PortA(char ModuleAddress); 


Returns 


Byte read. 




The function reads byte from Port Expander's PortA. 


Description 


Parameters: 




- ModuleAddress : Port Expander hardware address, see schematic at the 




bottom of this page 




Port Expander must be initialized. See Expanderjnit. 


Requires 


Port Expander's PortA should be configured as an input. See 




Expander_Set_DirectionPortA and Expander_Set_DirectionPortAB routines. 




// Read a byte from Port Expander's PORTA 




char read data; 


Example 


Expander Set DirectionPortA (0, OxFF) ; // set expander's porta to 




be input 




read data = Expander Read PortA(O); 



Expander_Read_PortB 



Prototype 


char Expander Read PortB (char ModuleAddress); 


Returns 


Byte read. 


Description 


The function reads byte from Port Expander's PortB. 

Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 


Requires 


Port Expander must be initialized. See Expanderjnit. 

Port Expander's PortB should be configured as input. See ExpanderSetDirec- 
tionPortB and Expander_Set_DirectionPortAB routines. 


Example 


// Read a byte from Port Expander's PORTB 
char read data; 

Expander Set DirectionPortB (0, OxFF) ; // set expander's 
portb to be input 

read data = Expander Read PortB (0); 
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Expander_Read_PortAB 



Prototype 


unsigned int Expander Read PortAB (char ModuleAddress); 


Returns 


Word read. 


Description 


The function reads word from Port Expander's ports. PortA readings are in the 
higher byte of the result. PortB readings are in the lower byte of the result. 

Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 


Requires 


Port Expander must be initialized. See Expanderjnit. 

Port Expander's PortA and PortB should be configured as inputs. See 
Expander_Set_DirectionPortA, Expander_Set_DirectionPortB and 
Expander_Set_DirectionPortAB routines. 


Example 


// Read a byte from Port Expander's PORTA and PORTB 
unsigned int read data; 

Expander Set DirectionPortAB (0, OxFFFF) ; // set expander's porta 
and portb to be input 

read data = Expander Read PortAB (0); 



Expander_Write_PortA 



Prototype 


void Expander Write PortA(char ModuleAddress, char Data ) ; 


Returns 


Nothing. 


Description 


The function writes byte to Port Expander's PortA. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data : data to be written 


Requires 


Port Expander must be initialized. See Expanderjnit. 

Port Expander's PortA should be configured as output. See 
Expander_Set_DirectionPortA and Expander_Set_DirectionPortAB routines. 


Example 


Expander Set DirectionPortA (0, 0x00 ) ; // set expander's 
porta to be output 

Expander Write PortA(0, OxAA) ; 
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Expander_Write_PortB 



Prototype 


void Expander Write PortB(char ModuleAddress, char Data ); 


Returns 


Nothing. 


Description 


The function writes byte to Port Expander's PortB. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data: data to be written 


Requires 


Port Expander must be initialized. See Expanderjnit. 

Port Expander's PortB should be configured as output. See 
Expander_Set_DirectionPortB and Expander_Set_DirectionPortAB routines. 


Example 


Expander Set DirectionPortB (0, 0x00 ) ; // set expander's 
portb to be output 

Expander Write PortB (0, 0x55); 



Expander_Write_PortAB 



Prototype 



Returns 



Description 



Requires 



Example 



void Expander_Write_PortAB (char ModuleAddress, unsigned int Data_ 



Nothing. 



The function writes word to Port Expander's ports. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data: data to be written. Data to be written to PortA are passed in Data's 
higher byte. Data to be written to PortB are passed in Data's lower byte 



Port Expander must be initialized. See Expanderjnit. 

Port Expander's PortA and PortB should be configured as outputs. See 
Expander_Set_DirectionPortA, Expander_Set_DirectionPortB and 
Expander_Set_DirectionPortAB routines. 



// Write a byte to Port Expander's PORTA and PORTB 

Expander Set DirectionPortAB (0, 0x0000) ; // set expander's 
porta and portb to be output 

Expander_Write_PortAB (0, 0xAA55) ; 
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Expander_Set_DirectionPortA 



Prototype 



Returns 



Description 



Requires 



Example 



void Expander_Set_DirectionPortA (char ModuleAddress, char Data_ 



Nothing. 



The function sets Port Expander's PortA direction. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data: data to be written to the PortA direction register. Each bit corresponds 
to the appropriate pin of the PortA register. Set bit configures the correspon- 
ding pin as an input. Cleared bit configures the corresponding pin as an output. 



Port Expander must be initialized. See Expanderjnit. 



// Set Port Expander's PORTA to be output 
Expander_Set_DirectionPortA(0, 0x00) ; 



Expander_Set_DirectionPortB 



Prototype 


void Expander Set DirectionPortB (char ModuleAddress, char Data ) ; 


Returns 


Nothing. 


Description 


The function sets Port Expander's PortB direction. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data: data to be written to the PortB direction register. Each bit corresponds 
to the appropriate pin of the PortB register. Set bit configures the correspon- 
ding pin as an input. Cleared bit configures the corresponding pin as an output. 


Requires 


Port Expander must be initialized. See Expanderjnit. 


Example 


// Set Port Expander's PORTB to be input 
Expander Set DirectionPortB (0, OxFF) ; 
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Expander_Set_DirectionPortAB 



Prototype 


void Expander Set DirectionPortAB (char ModuleAddress, unsigned 
int Direction) ; 


Returns 


Nothing. 


Description 


The function sets Port Expander's PortA and PortB direction. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Direction: data to be written to direction registers. Data to be written to the 
PortA direction register are passed in Direction's higher byte. Data to be 
written to the PortB direction register are passed in Direction's lower byte. 
Each bit corresponds to the appropriate pin of the PortA/PortB register. Set bit 
configures the corresponding pin as an input. Cleared bit configures the corre- 
sponding pin as an output. 


Requires 


Port Expander must be initialized. See Expanderjnit. 


Example 


// Set Port Expander's PORTA to be output and PORTB to be input 
Expander Set DirectionPortAB (0, OxOOFF) ; 



Expander_Set_PullUpsPortA 



Prototype 



Returns 



Description 



Requires 



Example 



void Expander_Set_PullUpsPortA (char ModuleAddress, char Data_ 



Nothing. 



The function sets Port Expander's PortA pull up/down resistors. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data: data for choosing pull up/down resistors configuration. Each bit 
corresponds to the appropriate pin of the PortA register. Set bit enables pull-up 
for corresponding pin. 



Port Expander must be initialized. See Expanderjnit. 



// Set Port Expander's PORTA pull-up resistors 
Expander_Set_PullUpsPortA(0, OxFF) ; 
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Expander_Set_PullUpsPortB 



Prototype 


void Expander Set PullUpsPortB (char ModuleAddress, char Data ) ; 


Returns 


Nothing. 


Description 


The function sets Port Expander's PortB pull up/down resistors. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Data: data for choosing pull up/down resistors configuration. Each bit 
corresponds to the appropriate pin of the PortB register. Set bit enables 
pull-up for corresponding pin. 


Requires 


Port Expander must be initialized. See Expanderjnit. 


Example 


// Set Port Expander's PORTB pull-up resistors 
Expander Set PullUpsPortB (0, OxFF) ; 



Expander_Set_PullUpsPortAB 



Prototype 


void Expander Set PullUpsPortAB (char ModuleAddress, unsigned int 

PullUps) ; 


Returns 


Nothing. 


Description 


The function sets Port Expander's PortA and PortB pull up/down resistors. 
Parameters: 

- ModuleAddress : Port Expander hardware address, see schematic at the 
bottom of this page 

- Puiiups : data for choosing pull up/down resistors configuration. PortA pull 
up/down resistors configuration is passed in Puiiups's higher byte. PortB pull 
up/down resistors configuration is passed in Puiiups's lower byte. Each bit 
corresponds to the appropriate pin of the PortA/PortB register. Set bit enables 
pull-up for corresponding pin. 


Requires 


Port Expander must be initialized. See Expanderjnit. 


Example 


// Set Port Expander's PORTA and PORTB pull-up resistors 
Expander Set PullUpsPortAB (0, OxFFFF) ; 
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The example demonstrates how to communicate with Port Expander MCP23S17. 
Note that Port Expander pins A2 A1 AO are connected to GND so Port Expander 
Hardware Address is o. 



// Port Expander module connections 

sbit SPExpanderRST at RCOJoit; 

sbit SPExpanderCS at RClJoit; 

sbit SPExpanderRST_Direction at TRISCOJoit; 

sbit SPExpanderCS_Direction at TRISClJoit; 

// End Port Expander module connections 



unsigned char i = 

void main ( ) { 
ANSEL = ; 
ANSELH = 0; 
TRISB = 0; 
PORTB = OxFF; 



0; 



// Configure AN pins as digital I/O 
// Set PORTB as output 



// If Port Expander Library uses SPI1 module 

SPI1 Init(); // Initialize SPI module used with PortExpander 

// If Port Expander Library uses SPI2 module 

// SPI2 Init(); // Initialize SPI module used with PortExpander 



Expander_Init (0) 



// Initialize Port Expander 



Expander_Set_DirectionPortA(0, 0x00); // Set Expander's PORTA to 
be output 

Expander_Set_DirectionPortB (0, OxFF) ; // Set Expander's PORTB to be 
input 

Expander_Set_PullUpsPortB (0, OxFF) ; // Set pull-ups to all of the 
Expander's PORTB pins 

while (1) { // Endless loop 

Expander_Write_PortA (0, i++) ; // Write i to expander's PORTA 
PORTB = Expander_Read_PortB (0) ; // Read expander's PORTB and 
write it to LEDs 

Delay_ms (100) ; 
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PS/2 LIBRARY 

The mikroC PRO for PIC provides a library for communication with the common 
PS/2 keyboard. 

Note: The library does not utilize interrupts for data retrieval, and requires the oscil- 
lator clock to be at least 6MHz. 

Note: The pins to which a PS/2 keyboard is attached should be connected to the 
pull-up resistors. 

Note: Although PS/2 is a two-way communication bus, this library does not provide 
MCU-to-keyboard communication; e.g. pressing the Caps Lock key will not turn on 
the Caps Lock LED. 

External dependencies of PS/2 Library 



The following vari- 
ables must be defined 
in all projects using 
PS/2 Library: 


Description: 


Example: 


extern sfr sbit 

PS2 Data; 


PS/2 Data line. 


RCO bit 


extern sfr sbit 

PS2 Clock; 


PS/2 Clock line. 


RC1 bit; 


extern sfr sbit 

PS2 Data Direction; 


Direction of the PS/2 Data pin. 


at TRISCO bit; 


extern sfr sbit 

PS2 Clock Direction; 


Direction of the PS/2 Clock pin. 


at TRISC1 bit; 



Library Routines 

- Ps2_Config 

- Ps2_Key_Read 
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Ps2_Config 




Prototype 


void Ps2 ConfigO ; 


Returns 


Nothing. 


Description 


Initializes the MCU for work with the PS/2 keyboard. 




Global variables: 




- ps2 Data: Data signal line 


Requires 


- ps2 clock: Clock signal line in 

- ps2 Data Direction: Direction of the Data pin 




- PS2 clock Direction: Direction of the Clock pin 




must be defined before using this function. 




sbit PS2 Data at RCO bit; 




sbit PS2 Clock at RC1 bit; 


Example 


sbit PS2 Data Direction at TRISCO bit; 
sbit PS2 Clock Direction at TRISC1 bit; 




Ps2 ConfigO; // Init PS/2 Keyboard 
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Ps2_Key_Read 



Prototype 


unsigned short Ps2 Key Read (unsigned short * value, unsigned short 

* special, unsigned short *pressed) ; 


Returns 


- i if reading of a key from the keyboard was successful 

- o if no key was pressed 


Description 


The function retrieves information on key pressed. 
Parameters: 

- value : holds the value of the key pressed. For characters, numerals, 
punctuation marks, and space value will store the appropriate ASCII code. 
Routine "recognizes" the function of Shift and Caps Lock, and behaves 
appropriately. For special function keys see Special Function Keys Table. 

- special : is a flag for special function keys (F1 , Enter, Esc, etc). If key pressed 
is one of these, special will be set to 1 , otherwise 0. 

- pressed : is set to 1 if the key is pressed, and if it is released. 


Requires 


PS/2 keyboard needs to be initialized. See Ps2_Config routine. 


Example 


unsigned short keydata = 0, special = 0, down = ; 

// Press Enter to continue: 
do { 

if (Ps2 Key Read ( Skeydata, Sspecial, Sdown) ) { 
if (down ss (keydata == 16)) break; 

} 
} while ( 1 ) ; 
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Special Function 


Keys 


Key 


Value returned 


F1 


1 


F2 


2 


F3 


3 


F4 


4 


F5 


5 


F6 


6 


F7 


7 


F8 


8 


F9 


9 


F10 


10 


F11 


11 


F12 


12 


Enter 


13 


Page Up 


14 


Page Down 


15 


Backspace 


16 


Insert 


17 


Delete 


18 


Windows 


19 


Ctrl 


20 


Shift 


21 


Alt 


22 


Print Screen 


23 


Pause 


24 


Caps Lock 


25 


End 


26 


Home 


27 


Scroll Lock 


28 



Num Lock 


29 


Left Arrow 


30 


Right Arrow 


31 


Up Arrow 


32 


Down Arrow 


33 


Escape 


34 


Tab 


35 
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Library Example 

This simple example reads values of the pressed keys on the PS/2 keyboard and 
sends them via UART 

unsigned short keydata = 0, special = 0, down = ; 

sbit PS2_Data at RCOJoit; 

sbit PS2_Clock at RClJoit; 

sbit PS2_Data_Direction at TRISCOJoit; 

sbit PS2_Clock_Direction at TRISClJoit; 

void main ( ) { 



ANSEL 

ANSELH 



0; 
0; 



// Configure AN pins as digital I/O 



UARTl_Init (19200) ; 
Ps2_Config() ; 
Delayjns (100) ; 
UARTl_Write_Text ( "Ready' 



// Initialize UART module at 19200 bps 

// Init PS/2 Keyboard 

// Wait for keyboard to finish 



do { 

if (Ps2_Key_Read (Skeydata, Sspecial, sdown) ) { 
if (down && (keydata == 16)) { // Backspace 

UARTl_Write (0x08) ; 
} 
else if (down && (keydata == 13) ) { // Enter 

UART1 Write('r'); // send carriage return to usart terminal 
//Usart Write ( ' n ' ) ; // uncomment this line if usart 
terminal also expects line feed 

// for new line transition 
} 

else if (down && ! special SS keydata) { 
UARTl_Write (keydata) ; 



Delay_ms (1 ) ; 
while (1); 



// debounce 
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PWM LIBRARY 

CCP module is available with a number of PIC MCUs. mikroC PRO for PIC provides library which 
simplifies using PWM HW Module. 

Note: Some MCUs have multiple CCP modules. In order to use the desired CCP library routine, 
simply change the number 1 in the prototype with the appropriate module number, i.e. 

PWM2_Start () ; 

Library Routines 

- PWMIJnit 

- PWM1_Set_Duty 

- PWM1_Start 

- PWM1_Stop 



PWM1 Init 



Prototype 


void PWM1 Init (long f req) ; 


Returns 


Nothing. 


Description 


Initializes the PWM module with duty ratio 0. Parameter freq is a desired PWM 
frequency in Hz (refer to device data sheet for correct values in respect with 
Fosc). 

This routine needs to be called before using other functions from PWM Library. 


Requires 


MCU must have CCP module. 

Note: Calculation of the PWM frequency value is carried out by the compiler, as 
it would produce a relatively large code if performed on the libary level. 
Therefore, compiler needs to know the value of the parameter in the compile time. 
That is why this parameter needs to be a constant, and not a variable. 


Example 


Initialize PWM module at 5KHz: 

PWMl Init (5000) ; 
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PWM1_Set_Duty 



Prototype 


void PWM1 Set Duty (unsigned short duty ratio); 


Returns 


Nothing. 


Description 


Sets PWM duty ratio. Parameter duty takes values from to 255, where is 
0%, 127 is 50%, and 255 is 100% duty ratio. Other specific values for duty ratio 
can be calculated as (Percent*255) /ioo. 


Requires 


MCU must have CCP module. PWM1_lnit must be called before using this routine. 


Example 


Set duty ratio to 75%: 

PWMl Set Duty (192) ; 



PWM1 Start 



Prototype 


void PWMl Start (void) ; 


Returns 


Nothing. 


Description 


Starts PWM. 


Requires 


MCU must have CCP module. PWM1_lnit must be called before using this routine. 


Example 


PWMl Start () ; 



PWM1_Stop 



Prototype 


void PWMl Stop (void) ; 


Returns 


Nothing. 


Description 


Starts PWM. 


Requires 


MCU must have CCP module. PWMIJnit must be called before using this rou- 
tine. PWM1_Start should be called before using this routine, otherwise it will have 
no effect as the PWM module is not running. 


Example 


PWMl Stop () ; 
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The example changes PWM duty ratio on RC1 and RC2 pins continually. If LED is 
connected to these pins, you can observe the gradual change of emitted light. 

unsigned short current_duty, old_duty, current_dutyl, old_dutyl; 



void InitMain ( 


ANSEL = 0; 


ANSELH = 0; 


PORTA = 255; 


TRISA = 2 55; 


PORTB = 




TRISB = 




PORTC = 




TRISC = 





) ! 



PWMl_Init (5000) ; 
PWM2 Init (5000) ; 



// Configure AN pins as digital I/O 



// configure PORTA pins as input 

// set PORTB to 

// designate PORTB pins as output 

// set PORTC to 

// designate PORTC pins as output 

// Initialize PWM1 module at 5KHz 

// Initialize PWM2 module at 5KHz 



void main ( ) { 
InitMain ( ) ; 
current_duty 
current_dutyl 



16; // initial value for current duty 
16; // initial value for current dutyl 



PWMlJStart () ; 

PWM2_Start () ; 

PWMl_Set_Duty (current_duty) ; 

PWM2_Set_Duty (current_dutyl) ; 



// start PWM1 

// start PWM2 

// Set current duty for PWM1 

// Set current duty for PWM2 



while (1) { 

if (RAOJoit) { 
Delay_ms (40) ; 
current duty++; 
PWMl_Set_Duty (current_duty) 



// endless loop 

// button on RAO pressed 

// increment current duty 



if (RAlJoit) { // button on RA1 pressed 

Delay_ms (40) ; 

current_duty--; // decrement current_duty 

PWMl_Set_Duty (current_duty) ; 
} 

if (RA2_bit) { // button on RA2 pressed 

Delay_ms (40) ; 

current dutyl++; // increment current_dutyl 

PWM2_Set_Duty (current_dutyl) ; 
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if (RA3_bit) { // button on RA3 pressed 

Delay_ms (40) ; 

current dutyl--; // decrement current dutyl 

PWM2_Set_Duty (current_dutyl) ; 



Delay_ms (5 ) 



// slow down change pace a little 



HW Connection 




vcc 



PWM demonstration 
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RS-485 LIBRARY 

RS-485 is a multipoint communication which allows multiple devices to be connect- 
ed to a single bus. The mikroC PRO for PIC provides a set of library routines for 
comfortable work with RS485 system using Master/Slave architecture. Master and 
Slave devices interchange packets of information. Each of these packets contains 
synchronization bytes, CRC byte, address byte and the data. Each Slave has 
unique address and receives only packets addressed to it. The Slave can never ini- 
tiate communication. It is the user's responsibility to ensure that only one device 
transmits via 485 bus at a time. The RS-485 routines require the UART module. Pins 
of UART need to be attached to RS-485 interface transceiver, such as LTC485 or 
similar (see schematic at the bottom of this page). 

Note: The library uses the UART module for communication. The user must initial- 
ize the appropriate UART module before using the RS-485 Library. For MCUs with 
two UART modules it is possible to initialize both of them and then switch by using 
the uart set Active function. See the UART Library functions. 

Library constants: 

- START byte value = 150 

- STOP byte value = 169 

-Address 50 is the broadcast address for all Slaves (packets containing address 50 
will be received by all Slaves except the Slaves with addresses 150 and 169). 

Note: Since some PIC18 MCUs have multiple UART modules, appropiate UART 
module must be initialized. Switching between UART modules in the UART library 
is done by the UART_Set_Active function (UART module has to be previously ini- 
tialized). 



External dependencies of RS-485 Library 



The following variable 
must be defined in all proj- 
ects using RS-485 Library: 


Description: 


Example: 


extern sfr sbit 

RS485 rxtx pin; 


Control RS^85 
Transmit/Receive operation 
mode 


sbit RS485 rxtx pin at 
RC2 bit; 


extern sfr sbit 

RS485 rxtx pin direc- 
tion; 


Direction of the RS-485 
Transmit/Receive pin 


sbit 

RS485 rxtx pin direc- 
tion at TRISC2 bit; 
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Library Routines 

- RS485master_lnit 

- RS485master_Receive 

- RS485master_Send 

- RS485slave_lnit 

- RS485slave_Receive 

- RS485slave Send 



RS485Master Init 



Prototype 


void RS485Master Init(); 


Returns 


Nothing. 


Description 


Initializes MCU as a Master for RS-485 communication. 


Requires 


Global variables: 

RS485 rxtx pin - this pin is connected to RE/DE input of RS-485 transceiv- 
er(see schematic at the bottom of this page). RE/DE signal controls RS-485 
transceiver operation mode. 

RS485 rxtx pin direction - direction of the RS-485 Transmit/Receive pin 

must be defined before using this function. 

UART HW module needs to be initialized. See UARTIJnit. 


Example 


// RS485 module pinout 

sbit RS485 rxtx pin direction at RC2 bit; // transmit/receive 

control set to P0RTC.B2 

// Pin direction 

sbit RS485 rxtx pin direction at TRISC2 bit; // RxTx pin direc- 
tion set as output 

UART1 Init (9600); // initialize UART module 

RS485Master Init(); // intialize MCU as a Master for RS-485 

communication 
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RS485Master Receive 



Prototype 


void RS485Master Receive (char *data buffer); 


Returns 


Nothing. 


Description 


Receives messages from Slaves. Messages are multi-byte, so this routine must 
be called for each byte received. 

Parameters: 

- data buffer : 7 byte buffer for storing received data, in the following manner: 

- data[ o. .2] : message content 

- data[ 3] : number of message bytes received, 1-3 

- data[ 4] : is set to 255 when message is received 

- data[ 5] : is set to 255 if error has occurred 

- data[ 6] : address of the Slave which sent the message 

The function automatically adjusts data[ 4] and data[ 5] upon every received 
message. These flags need to be cleared by software. 


Requires 


MCU must be initialized as a Master for RS-485 communication. See 
RS485master_lnit. 


Example 


char msg[ 8] ; 

RS485Master Receive (msg) ; 



RS485Master Send 



Prototype 


void RS485Master Send (char *data buffer, char datalen, char 
Slave address); 


Returns 


Nothing. 


Description 


Sends message to Slave(s). Message format can be found at the bottom of this 
page. 

Parameters: 

- data buffer: data to be sent 

- datalen : number of bytes for transmition. Valid values: 0...3. 

-slave address: Slave(s) address 


Requires 


MCU must be initialized as a Master for RS-485 communication. See 

RS485Master_lnit. 

It is the user's responsibility to ensure (by protocol) that only one device sends 

data via 485 bus at a time. 


Example 


char msg[ 8] ; 

// send 3 bytes of data to Slave with address 0x12 
RS485Master Send (msg, 3, 0x12); 
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RS485slave Init 



Prototype 


void RS485Slave Init (char Slave address); 


Returns 


Nothing. 


Description 


Initializes MCU as a Slave for RS-485 communication. 
Parameters: 

- slave address : Slave address 


Requires 


Global variables: 

RS485 rxtx pin - this pin is connected to RE/DE input of RS-485 transceiv- 
er(see schematic at the bottom of this page). RE/DE signal controls RS-485 
transceiver operation mode. Valid values: : (for transmitting) and o (for receiv- 
ing) 

RS485 rxtx pin direction - direction of the RS-485 Transmit/Receive pin 

must be defined before using this function. 

UART HW module needs to be initialized. See UARTIJnit. 


Example 


// RS485 module pinout 

sbit RS485 rxtx pin at RC2 bit; // transmit/receive control 

set to P0RTC.B2 

// Pin direction 

sbit RS485 rxtx pin direction at TRISC2 bit; // RxTx pin direc- 
tion set as output 

UART1 Init (9600); // initialize UART module 
RS485Slave Init (160); // intialize MCU as a Slave 
for RS-485 communication with address 160 
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RS485slave_ 


Receive 


Prototype 


void RS485Slave Receive (char *data buffer); 


Returns 


Nothing. 


Description 


Receives messages from Master. If Slave address and Message address field 
don't match then the message will be discarded. Messages are multi-byte, so this 
routine must be called for each byte received. 

Parameters: 

- data buffer : 6 byte buffer for storing received data, in the following manner: 

- data[ o. .2] : message content 

- data[ 3] : number of message bytes received, 1-3 

- data[ 4] : is set to 255 when message is received 

- data[ 5] : is set to 255 if error has occurred 

The function automatically adjusts data[ 4] and data[ 5] upon every received 
message. These flags need to be cleared by software. 


Requires 


MCU must be initialized as a Slave for RS-485 communication. See 
RS485slave_lnit. 


Example 


char msg[ 8] ; 
RS485Slave Read(msg); 
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RS485slave_ 


Send 


Prototype 


void RS485Slave Send (char *data buffer, char datalen); 


Returns 


Nothing. 


Description 


Sends message to Master. Message format can be found at the bottom of this 
page. 

Parameters: 

- data buffer: data to be sent 

- datalen : number of bytes for transmition. Valid values: 0...3. 


Requires 


MCU must be initialized as a Slave for RS-485 communication. See 
RS485slave_lnit. It is the user's responsibility to ensure (by protocol) that only 
one device sends data via 485 bus at a time. 


Example 


char msg[ 8] ; 

// send 2 bytes of data to the Master 
RS485Slave Send(msg, 2); 



Library Example 

This is a simple demonstration of RS485 Library routines usage. 

Master sends message to Slave with address 160 and waits for a response. The Slave accepts 
data, increments it and sends it back to the Master. Master then does the same and sends incre- 
mented data back to Slave, etc. 

Master displays received data on PORTB, while error on receive (OxAA) and number of consec- 
utive unsuccessful retries are displayed on PORTD. Slave displays received data on PORTB, 
while error on receive (OxAA) is displayed on PORTD. Hardware configurations in this example 
are made for the EasyPIC5 board and 16F887. 
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RS485 Master code: 



char dat[ 10] 
char i , j ; 



// buffer for receving/sending messages 



sbit rs485_rxtx pin at RC2 bit; // set transcieve pin 

sbit rs485 rxtx pin direction at TRISC2 bit; // set transcieve pin 
direction 

// Interrupt routine 
void interrupt () { 

RS485Master Receive (dat ) ; 



void main ( ) { 
long cnt = 0; 



ANSEL 


= 0; 


ANSELH 


= 0; 


PORTB 


= 0; 


PORTD 


= 0; 


TRISB 


= 0; 


TRISD 


= 0; 



// Configure AN pins as digital I/O 



UARTl_Init (9600) 
Delayjns (100) ; 



// initialize UART1 module 



RS485Master_Init () ; 

dat[ 0] = OxAA; 

dat[ 1] = OxFO; 

dat[ 2] = OxOF; 

dat[ 4] =0; 

dat[ 5] =0; 

dat[ 6] =0; 



// initialize MCU as Master 



// ensure that message received flag is 
// ensure that error flag is 



RS485Master Send (dat, 1, 160) ; 



PIE1.RCIE = 1; 
PIE2.TXIE = 0; 
INTCON.PEIE = 1; 
INTCON.GIE = 1; 



// enable interrupt on UART1 receive 

// disable interrupt on UART1 transmit 

// enable peripheral interrupts 

// enable all interrupts 



while (1){ 



cnt++; 



// upon completed valid message receiving 
// data[ 4] is set to 255 
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if (dat[ 5] ) { 
PORTD = OxAA; 



if (dat[ 4] ) { 
cnt = 0; 
dat[ 4] = 
j = dat[ 3] 
for (i = 1 
PORTB = 



// if an error detected, signal it 
// by setting portd to OxAA 

// if message received successfully 

// clear message received flag 

// show data on PORTB 



i <= dat[ 3] ; i++) 
dat[ i-1] ; 



dat[ 0] = dat[ 0] +1; 

Delay_ms (1) ; 

RS485Master Send (dat, 1, 160) ; 



// increment received dat[ 0] 
// send back to master 



} 
if (cnt > 100000) { 
PORTD ++; 
cnt = 0; 

RS485Master_Send(dat, 1, 160) ; 
if (PORTD > 10) 

RS485Master_Send (dat, 1, 50) 
address 



// if sending failed 10 times 
// send message on broadcast 



) 



RS485 Slave code: 

char dat[ 9] ; 
char i , j ; 



// function to be properly linked. 



// buffer for receving/sending messages 



sbit rs485 rxtx pin at RC2 bit; // set transcieve pin 

sbit rs485 rxtx pin direction at TRISC2_bit; // set transcieve pin 
direction 

// Interrupt routine 
void interrupt () { 
RS485Slave Receive (dat ) ; 



void main ( ) { 
ANSEL = ; 
ANSELH = 0; 



// Configure AN pins as digital I/O 



PORTB 
PORTD 
TRISB 
TRISD 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 41 7 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



UARTl^Init (9600) ; 
Delayjns (100) ; 
RS485Slave Init(160); 



dat[ 4] = 
dat[ 5] = 
dat[ 6] = 



PIE1.RCIE = 1; 
PIE2.TXIE = 0; 
INTCON.PEIE = 1; 
INTCON.GIE = 1; 

while (1) { 

if (dat[ 5] ) { 
PORTD = OxAA; 
dat[ 5] = 0; 



if (dat[ 4] ) { 

dat[ 4] = 

j = dat[ 3] 

for (i - 1 

PORTB 



// initialize UART1 module 

// Intialize MCU as slave, address 160 

// ensure that message received flag is 
// ensure that message received flag is 
// ensure that error flag is 

// enable interrupt on UART1 receive 
// disable interrupt on UART1 transmit 
// enable peripheral interrupts 
// enable all interrupts 



// if an error detected, signal it by 
// setting portd to OxAA 



// upon completed valid message receive 
// data[ 4] is set to OxFF 



i <= dat[ 3] ;i + + ){ 
dat[ i-1] ; 



dat[ 0] = dat[ 0] +1; 
Delay_ms (1) ; 
RS485Slave Send(dat,l) 



// increment received dat[ 0] 
// and send it back to master 
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HW Connection 



Shielded pair 

no longer than 300m 




Example of interfacing PC to 8051 MCU via RS485 bus with LTC485 as 

RS-485 transceiver 
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Message format and CRC calculations 

Q: How is CRC checksum calculated on RS485 Master side? 

START_BYTE = 0x96; // 10010110 
STOP_BYTE = 0xA9; // 10101001 

PACKAGE : 



START_BYTE 0x96 

ADDRESS 

DATALEN 

[ DATA1] 

[ DATA2] 

[ DATA3] 

CRC 

STOP BYTE 0xA9 



// if exists 
// if exists 
// if exists 



DATALEN bits 

bit7 = 1 MASTER SENDS 

SLAVE SENDS 
bit6 = 1 ADDRESS WAS XORed with 1, IT WAS EQUAL TO START_BYTE or 
STOP_BYTE 

ADDRESS UNCHANGED 
bit5 = FIXED 

bit4 = 1 DATA3 (if exists) WAS XORed with 1, IT WAS EQUAL TO 
START_BYTE or STOP_BYTE 

DATA3 (if exists) UNCHANGED 
bit3 = 1 DATA2 (if exists) WAS XORed with 1, IT WAS EQUAL TO 
START_BYTE or STOP_BYTE 

DATA2 (if exists) UNCHANGED 
bit2 = 1 DATA1 (if exists) WAS XORed with 1, IT WAS EQUAL TO 
START_BYTE or STOP_BYTE 

DATA1 (if exists) UNCHANGED 
bitlbitO = to 3 NUMBER OF DATA BYTES SEND 



CRC generation 



crc_send 
crc send 
crc send 
crc send 
crc send 



datalen A address; 



data[ 0] 
data[ 1] 
data[ 2] 
-crc send; 



// if exists 
// if exists 
// if exists 



if ( (crc_send = 
crc send++; 



START BYTE) | | (crc send 



STOP BYTE) ) 



NOTE: DATALEN<4 . . 0> can not take the START_BYTE<4 . . 0> or 
STOP BYTE<4..0> values. 
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SOFTWARE l 2 C LIBRARY 

The mikroC PRO for PIC provides routines for implementing Software l 2 C commu- 
nication. These routines are hardware independent and can be used with any MCU. 

The Software l 2 C library enables you to use MCU as Master in l 2 C communication. 
Multi-master mode is not supported. 

Note: This library implements time-based activities, so interrupts need to be dis- 
abled when using Software l 2 C. 

Note: All Software l 2 C Library functions are blocking-call functions (they are waiting 
for l 2 C clock line to become logical one). 

Note: The pins used for the Software l 2 C communication should be connected to 
the pull-up resistors. Turning off the LEDs connected to these pins may also be 
required. 

External dependecies of Soft_l2C Library 



The following variables 

must be defined in all 

projects using Software 

l 2 C Library: 


Description: 


Example: 


extern sbit 

Soft_I2C_Scl; 


Soft l 2 C Clock line. 


RC3 bit; 


extern sbit 

Soft I2C Sda; 


Soft l 2 C Data line. 


RC4 bit; 


extern sbit 

Soft I2C Scl Direction; 


Direction of the Soft 
l 2 C Clock pin. 


sbit Soft I2C Scl Direction 
at TRISC3 bit; 


extern sbit 

Soft I2C Sda Direction; 


Direction of the Soft 
l 2 C Data pin. 


sbit Soft I2C Sda Direction 
at TRISC4 bit; 



Library Routines 

- SoftJ2C_lnit 

- Soft_l2C_Start 

- Soft_l2C_Read 

- Soft_l2C_Write 

- Soft_l2C_Stop 

- Soft I2C Break 
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Soft I2C Init 



Prototype 


void Soft I2C Init () ; 


Returns 


Nothing. 


Description 


Configures the software l L C module. 




Global variables: 




- soft 12c Sci: Soft l L C clock line 


Requires 


- soft 12c sda: Soft l L C data line 

- soft 12c Sci Pin Direction: Direction of the Soft l L C clock pin 




- Soft 12c sda Pin Direction: Direction of the Soft l L C data pin 




must be defined before using this function. 




// Software I2C connections 




sbit Soft I2C Sci at RC3 bit; 




sbit Soft I2C Sda at RC4 bit; 




sbit Soft I2C Sci Direction at TRISC3 bit; 


Example 


sbit Soft I2C Sda Direction at TRISC4 bit; 




// End Software I2C connections 




Soft I2C Init () ; 



Soft I2C Start 



Prototype 


void Soft I2C Start (void); 


Returns 


Nothing. 


Description 


Determines if the I^C bus is free and issues START signal. 


Requires 


Software I^C must be configured before using this function. See Soft_l2C_lnit 
routine. 


Example 


// Issue START signal 
Soft I2C Start () ; 
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Soft I2C Read 



Prototype 


unsigned short Soft I2C Read (unsigned int ack); 


Returns 


One byte from the Slave. 


Description 


Reads one byte from the slave. 

Parameters: 

- ack: acknowledge signal parameter. If the ack==o not 
acknowledge signal will be sent after reading, otherwise the 
acknowledge signal will be sent. 


Requires 


Soft l L C must be configured before using this function. See Soft_l2C_lnit routine. 
Also, START signal needs to be issued in order to use this function. See 
Soft_l2C_Start routine. 


Example 


unsigned short take; 

// Read data and send the not acknowledge signal 
take = Soft I2C Read(O); 



Soft I2C Write 



Prototype 


unsigned short Soft I2C Write (unsigned short Data ); 


Returns 


o if there were no errors. 
- 1 if write collision was detected on the l L C bus. 


Description 


Sends data byte via the l L C bus. 

Parameters: 

- Data: data to be sent 


Requires 


Soft l L C must be configured before using this function. See Soft_l2C_lnit routine. 
Also, START signal needs to be issued in order to use this function. See 
Soft_l2C_Start routine. 


Example 


unsigned short data, error; 

error = Soft I2C Write (data); 
error = Soft I2C Write (0xA3); 
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Soft_l2C_Stop 



Prototype 


void Soft I2C Stop (void) ; 


Returns 


Nothing. 


Description 


Issues STOP signal. 


Requires 


Soft I^C must be configured before using this function. See Soft_l2C_lnit routine. 


Example 


// Issue STOP signal 
Soft I2C StopO ; 



Soft I2C Break 



Prototype 


void Soft I2C Break (void); 


Returns 


Nothing. 


Description 


All Software I^C Library functions can block the program flow (see note at the top 
of this page). Calling this routine from interrupt will unblock the program execu- 
tion. This mechanism is similar to WDT 

Note: Interrupts should be disabled before using Software I^C routines again 
(see note at the top of this page). 


Requires 


Nothing. 


Example 


// Software I2C connections 
sbit Soft_I2C_Scl at RC0_bit; 
sbit Soft I2C Sda at RC1 bit; 
sbit Soft I2C Scl Direction at TRISCO bit; 
sbit Soft I2C Sda Direction at TRISC1 bit; 
// End Software I2C connections 

char counter = 0; 

void interrupt { 

if (INTCON.T0IF) { 

if (counter >= 20) { 

Soft I2C Break () ; 

counter = 0; // reset counter 
} 
else 

counter++; // increment counter 

INTCON.T0IF = 0; // Clear TimerO overflow interrupt flag 
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Example 



void main ( ) { 

OPTION_REG = 0x04; // TMRO prescaler set to 1:32 



// try Soft I2C Init with blocking prevention mechanism 
INTCON.GIE = 1; // Global interrupt enable 
INTCON.T0IE = 1; // Enable TimerO overflow interrupt 
Soft_I2C_Init () ; 
INTCON.GIE =0; // Global interrupt disable 



Library Example 

The example demonstrates Software l L C Library routines usage. The PIC MCU is 
connected (SCL, SDA pins) to PCF8583 RTC (real-time clock). Program reads date 
and time are read from the RTC and prints it on Led. 



char seconds, minutes, hours, day, month, year; 
variables 



// Global date/time 



// Software I2C connections 
sbit Soft_I2C_Scl at RC3_bit; 

sbit Soft_I2C_Sda at RC4_bit; 

sbit Soft_I2C_Scl_Direction at TRISC3_bit; 
sbit Soft_I2C_Sda_Direction at TRISC4_bit; 
// End Software I2C connections 



// LCD module connections 
sbit LCD_RS at RB4_bit; 
sbit LCD_EN at RB5_bit; 
sbit LCD_D4 at RBOJoit; 
sbit LCD_D5 at RBl_bit; 
sbit LCD_D6 at RB2_bit; 
sbit LCD_D7 at RB3_bit; 

sbit LCD_RS_Direction at TRISB4_bit; 
sbit LCD_EN_Direction at TRISB5_bit; 
sbit LCD D4 Direction at TRISBO bit; 
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sbit LCD_D5_Direction at TRISBlJoit; 
sbit LCD_D6_Direction at TRISB2_bit; 
sbit LCD_D7_Direction at TRISB3_bit; 
// End LCD module connections 



// 

(PCF8583) 
void Read_Time () { 

Soft_I2C_Start () ; 
Soft_I2C_Write (OxAO) ; 
Soft_I2C_Write (2) ; 
Soft_I2C_Start () ; 
Soft I2C Write (OxAl); 



Reads time and date information from RTC 



// Issue start signal 

// Address PCF8583, see PCF8583 datasheet 

// Start from address 2 

// Issue repeated start signal 

// Address PCF8583 for reading R/W=l 



seconds = Sof t_I2C_Read (1) ; 
minutes = Sof t_I2C_Read ( 1 ) ; 
hours = Soft_I2C_Read(l) ; 
day = Soft_I2C_Read(l) ; 
month = Soft_I2C_Read(0) ; 
Soft_I2C_Stop () ; 



// Read seconds byte 

// Read minutes byte 

// Read hours byte 

// Read year/day byte 

// Read weekday/month byte 

// Issue stop signal 



} 



// Formats date and time 

void Transf orm_Time ( ) { 

seconds = ((seconds & OxFO) >> 4)*10 + (seconds & OxOF) ; // 
Transform seconds 

minutes = ((minutes S OxFO) >> 4)*10 + (minutes & OxOF) 
Transform months 

hours = ((hours S OxFO) >> 4)* 10 + (hours & OxOF) ; 
Transform hours 

year = (day S OxCO) » 6; 
Transform year 

day = ((day & 0x30) » 4)* 10 + (day & OxOF); 
Transform day 

month = ((month S 0x10) >> 4)* 10 + (month & OxOF); 
Transform month 
} 



Output values to LCD 



// 
// 
// 
// 
// 



// 

void Display_Time ( ) { 



Lcd_Chr(l, 6, (day / 10) + 48); // Print tens digit of day 
variable 

Lcd_Chr(l, 7, (day % 10) + 48); // Print oness digit of day 
variable 

Lcd_Chr(l, 9, (month / 10) + 48); 

Lcd_Chr (1,10, (month % 10) + 48); 

Led Chr(l,15, year + 56); // Print year vaiable + 8 
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(start from year 2008) 



Lcd_Chr(2, 6, 
Lcd_Chr(2, 7, 
Lcd_Chr(2, 9, 
Lcd_Chr (2,10, 
Lcd_Chr (2,12, 
Led Chr (2, 13, 



(hours / 


10) 


+ 


48) 


(hours % 


10) 


+ 


48) 


(minutes 


/ 10) 


+ 


48) 


(minutes 


% 10) 


+ 


48) 


(seconds 


/ 10) 


+ 


48) 


(seconds 


% 10) 


+ 


48) 



// 

void Init Main ( ) { 



Performs project-wide init 



TRISB = 0; 

PORTB = OxFF; 

TRISB = Oxff; 

ANSEL = ; 

ANSELH = 0; 

Soft_I2C_Init () ; 

Lcd_Init () ; 

Lcd_Cmd (_LCD_CLEAR) ; 

Led Cmd ( LCD CURSOR OFF); 



// Configure AN pins as digital I/O 

// Initialize Soft I2C communication 
// Initialize LCD 
// Clear LCD display 
// Turn cursor off 



LcdjDut ( 1 , 1 , " Date : " ) ; 
Lcd_Chr (1,8, ' : ' ) ; 
Lcd_Chr (1,11, ' : ' ) ; 
Lcd_Out (2,1, "Time : " ) ; 
Lcd_Chr (2,8,':'); 
Lcd_Chr (2,11, ' : ') ; 
Led Out (1,12, "200") ; 



// Prepare and output static text on LCD 



// 

void main ( ) { 



Main procedure 



Delay_ms (2000) ; 
Init Main () ; 



// Perform initialization 



while (1) { 

Read_Time () ; 
Transform Time(); 
Display_Time () ; 

Delayjns (1000) ; 



// Endless loop 

// Read time from RTC(PCF8583) 

// Format date and time 

// Prepare and display on LCD 

// Wait 1 second 
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SOFTWARE SPI LIBRARY 

The mikroC PRO for PIC provides routines for implementing Software SPI commu- 
nication. These routines are hardware independent and can be used with any MCU. 
The Software SPI Library provides easy communication with other devices via SPI: 
A/D converters, D/A converters, MAX7219, LTC1290, etc. 

Library configuration: 

- SPI to Master mode 

- Clock value = 20 kHz. 

- Data sampled at the middle of interval. 

- Clock idle state low. 

- Data sampled at the middle of interval. 

- Data transmitted at low to high edge. 

Note: The Software SPI library implements time-based activities, so interrupts need 
to be disabled when using it. 

External dependencies of Software SPI Library 



The following variables 

must be defined in all 

projects using Software 

SPI Library: 


Description: 


Example: 


extern sfr sbit 

SoftSpi SDI; 


Data In line. 


RC4 bit; 


extern sfr sbit 

SoftSpi SDO; 


Data Out line. 


RC5 bit; 


extern sfr sbit 

SoftSpi CLK; 


Clock line. 


RC3 bit; 


extern sfr sbit 

SoftSpi SDI Direction; 


Direction of the Data In pin. 


SoftSpi SDI Direction 
at TRISC4 bit; 


extern sfr sbit 

SoftSpi SDO Direction; 


Direction of the Data Out pin 


sbit 

SoftSpi SDO Direction 
at TRISC5 bit; 


extern sfr sbit 

SoftSpi CLK Direction; 


Direction of the Clock pin. 


sbit 

SoftSpi CLK Direction 



428 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 7 
Libraries 



Library Routines 

- SoftSpilnit 

- SoftSpiRead 

- Soft_Spi_Write 



Soft_Spi_lnit 



Prototype 


void Soft SPI Init(); 


Returns 


Nothing. 


Description 


Configures and initializes the software SPI module. 


Requires 


Global variables 

- Chip Select 

- SoftSpi SDI 

- SoftSpi SDO 

- SoftSpi CLK 

- Chip Select 

- SoftSpi SDI 

- SoftSpi SDO 

- SoftSpi CLK 

must be defined 


Chip Select line 

Data in line 

Data out line 

Data clock line 
Direction: Direction of the Chip Select pin 
Direction: Direction of the Data in pin 
Direction: Direction of the Data out pin 
Direction: Direction of the Data clock pin 

before using this function. 


Example 


// Software SPI module connections 
sbit Chip Select at RCO bit; 
sbit SoftSpi SDI at RC4 bit; 
sbit SoftSpi SDO at RC5 bit; 
sbit SoftSpi CLK at RC3 bit; 

sbit Chip Select Direction at TRISCO bit; 
sbit SoftSpi SDI Direction at TRISC4 bit; 
sbit SoftSpi SDO Direction at TRISC5 bit; 
sbit SoftSpi CLK Direction at TRISC3 bit; 
// End Software SPI module connections 

Soft SPI Init(); // Init Soft SPI 
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Soft_Spi_Read 


Prototype 


unsigned short Soft SPI Read(char sdata); 


Returns 


Byte received via the SPI bus. 




This routine performs 3 operations simultaneously. It provides clock for the Soft- 
ware SPI bus, reads a byte and sends a byte. 


Description 


Parameters: 




sdata: data to be sent. 


Requires 


Soft SPI must be initialized before using this function. See SoftSPIInit routine. 




unsigned short data read; 
char data send; 


Example 


// Read a byte and assign it to data read variable 

// (data send byte will be sent via SPI during the Read opera- 




tion) 

data read = Soft SPI Read (data send); 



Soft SPI Write 



Prototype 


void Soft SPI Write (char sdata); 


Returns 


Nothing. 


Description 


This routine sends one byte via the Software SPI bus. 

Parameters: 

sdata: data to be sent. 


Requires 


Soft SPI must be initialized before using this function. See SoftSPIInit routine. 


Example 


// Write a byte to the Soft SPI bus 
Soft SPI Write (OxAA); 
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Library Example 

This code demonstrates using library routines for Soft_SPI communication. Also, 
this example demonstrates working with Microchip's MCP4921 12-bit D/A convert- 
er. 

// DAC module connections 
sbit Chip_Select at RCOJoit; 
sbit SoftSpi_CLK at RC3_bit; 
sbit SoftSpi_SDI at RC4_bit; 
sbit SoftSpi_SDO at RC5_bit; 

sbit Chip_Select_Direction at TRISCOJoit; 
sbit SoftSpi_CLK_Direction at TRISC3_bit; 
sbit SoftSpi_SDI_Direction at TRISC4_bit; 
sbit SoftSpi_SDO_Direction at TRISC5_bit; 
// End DAC module connections 

unsigned int value; 

void InitMain() { 

TRISBO_bit = 1; // Set RAO pin as input 

TRISBlJoit = 1; // Set RA1 pin as input 

Chip_Select =1; // Deselect DAC 

Chip_Select_Direction = 0; // Set CS# pin as Output 

Soft_SPI_Init () ; // Initialize Soft_SPI 

} 

// DAC increments (0..4095) — > output voltage (O..Vref) 
void DACjDutput (unsigned int valueDAC) { 
char temp; 

Chip_Select =0; // Select DAC chip 

// Send High Byte 

temp = (valueDAC » 8) & OxOF;// Store valueDAC[ 11.. 8] to temp[ 3..0] 
temp |= 0x30; // Define DAC setting, see MCP4921 datasheet 
Soft_SPI_Write (temp) ; // Send high byte via Soft SPI 

// Send Low Byte 

temp = valueDAC; // Store valueDAC[ 7 . . 0] to temp[ 7 . . 0] 

Soft_SPI_Write (temp) ; // Send low byte via Soft SPI 

Chip_Select =1; // Deselect DAC chip 
} 

void main ( ) { 

ANSEL = 0; // turn off analog inputs 
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ANSELH = 0; 
InitMain ( ) ; 
value = 2048; 

while (1) { 



// Perform main initialization 

// When program starts, DAC gives 

// the output in the mid-range 

// Endless loop 



if ((RA0_bit) && (value < 4095)) { // If RAO button is pressed 
value++; // increment value 

} 
else { 

if ((RAlJoit) && (value > 0)) { //If RA1 button is pressed 
value--; // decrement value 

} 



DAC_Output (value) 
Delay_ms (1 ) ; 



// Send value to DAC chip 
// Slow down key repeat pace 
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SOFTWARE UART LIBRARY 

The mikroC PRO for PIC provides routines for implementing Software UART com- 
munication. These routines are hardware independent and can be used with any 
MCU. The Software UART Library provides easy communication with other devices 
via the RS232 protocol. 

Note: The Software UART library implements time-based activities, so interrupts 
need to be disabled when using it. 

Library Routines 

- Soft_Uart_lnit 

- SoftUartRead 

- Soft_Uart_Write 

- Soft Uart Break 
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Soft UART Init 



Prototype 


char Soft UART Init (char *port, char rx pin, char tx pin, 
unsigned long baud rate, char inverted) ; 


Returns 


- 2 - error, requested baud rate is too low 

- 1 - error, requested baud rate is too high 

- o - successful initialization 


Description 


Configures and initializes the software UART module. 
Parameters: 

- port: port to be used. 

- rx pin: sets rx_pin to be used. 

- tx pin: sets tx_pin to be used. 

- baud rate: baud rate to be set. Maximum baud rate depends on the MCU's 
clock and working conditions. 

- inverted: inverted output flag. When set to a non-zero value, inverted logic 
on output is used. 

Software UART routines use Delay_Cyc routine. If requested baud rate is too low 
then calculated parameter for calling Delay eye exceeeds Delay eye argument 
range. 

If requested baud rate is too high then rounding error of Delay eye argument cor- 
rupts Software UART timings. 


Requires 


Nothing. 


Example 


This will initialize software UART and establish the communication at 9600 bps: 

char error; 

error = Soft UART Init(SPORTC, 7, 6, 14400, 0); // Initialize 
Soft UART at 9600 bps 
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Soft UART Read 



Prototype 


char Soft UART Read (char * error); 


Returns 


Byte received via UART. 


Description 


The function receives a byte via software UART. 

This is a blocking function call (waits for start bit). Programmer can unblock it by 
calling Soft_UART_Break routine. 

Parameters: 

- error: Error flag. Error code is returned through this variable. 

- no error 

1 - stop bit error 

255 - user abort, Soft_UART_Break called 


Requires 


Software UART must be initialized before using this function. See the 
SofMJARTJnit routine. 


Example 


char data, error; 

// wait until data is received 
do 

data = Soft UART Read ( Serror ) ; 
while (error) ; 

// Now we can work with data: 
if (data) { . . .} 
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Soft UART Write 



Prototype 


void Soft UART Write (char udata); 


Returns 


Nothing. 


Description 


This routine sends one byte via the Software UART bus. 

Parameters: 

- udata : data to be sent. 


Requires 


Software UART must be initialized before using this function. See the 
SofMJARTJnit routine. 

Be aware that during transmission, software UART is incapable of receiving data - 
data transfer protocol must be set in such a way to prevent loss of information. 


Example 


char some byte = OxOA; 

// Write a byte via Soft Uart 
Soft UART Write (some byte); 



Soft Uart Break 



Prototype 


void Soft UART Break (); 


Returns 


Nothing. 


Description 


Soft_UART_Read is blocking routine and it can block the program flow. Calling 
this routine from the interrupt will unblock the program execution. This mecha- 
nism is similar to WDT 

Note: Interrupts should be disabled before using Software UART routines again 
(see note at the top of this page). 


Requires 


Nothing. 


Example 


char datal, error, counter = 0; 

void interrupt ( ) { 

if (INTCON.TOIF) { 

if (counter >= 20) { 

Soft UART Break ( ) ; 

counter =0; // reset counter 
} 
else 

counter++; // increment counter 

INTCON.TOIF = 0; // Clear TimerO overflow interrupt flag 

} 
} 
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void main ( ) { 




OPTION REG = 0x04; // TMRO prescaler set to 1:32 




if (Soft UART Init (&PORTC, 7, 6, 9600, 0) = 0) 




Soft UART Write (0x55) ; 


Example 






// try Soft UART Read with blocking prevention mechanism 




INTCON.GIE = 1; // Global interrupt enable 




INTCON.T0IE = 1; // Enable TimerO overflow interrupt 




datal = Soft UART Read (Serror) ; 




INTCON.GIE =0; // Global interrupt disable 
} 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 437 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



Library Example 

This example demonstrates simple data exchange via software UART If MCU is 
connected to the PC, you can test the example from the mikroC PRO for PIC 
USART Terminal Tool. 



char i, error, byte_read; 

void main ( ) { 

ANSEL = 0; 
ANSELH = 0; 



// Auxiliary variables 



// Configure AN pins as digital I/O 



TRISB = 0x0 0; 
PORTB = 0; 



// Set PORTB as output (error signalization) 
// No error 



error = Sof t_UART_Init ( &PORTC, 7, 6, 14400, 0); // Initialize Soft 
UART at 9 60 bps 
if (error > 0) { 

PORTB = error; // Signalize Init error 

while(l); // Stop program 

} 
Delay_ms (100) ; 

for (i = 'z'; i >= 'A'; i — ) { // Send bytes from ' z' downto 'A' 
Soft_UART_Write (i) ; 
Delay_ms (100) ; 



while (1) { 

byte_read = Sof t_UART_Read ( serror ) 
test error flag 

if (error) // If error was detected 

PORTB = error; // signal it on PORTB 

else 

Sof t_UART_Write (byte_read) ; 
ed, return byte read 

} 
} 



// Endless loop 

// Read byte, then 



// If error was not detect- 
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SOUND LIBRARY 

The mikroC PRO for PIC provides a Sound Library to supply users with routines necessary for 
sound signalization in their applications. Sound generation needs additional hardware, such as 
piezo-speaker (example of piezo-speaker interface is given on the schematic at the bottom of this 
page). 

Library Routines 

- Soundjnit 

- Sound_Play 

Sound Init 



Prototype 


void Sound Init (char *snd port, char snd pin); 


Returns 


Nothing. 


Description 


Configures the appropriate MCU pin for sound generation. 
Parameters: 

- snd port: sound output port address 

- snd pin: sound output pin 


Requires 


Nothing. 


Example 


// Initialize the pin RD3 for playing sound 
Sound Init(&PORTD, 3); 
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Sound_Play 



Prototype 


void Sound Play (unsigned freq in hz, unsigned duration ms) ; 


Returns 


Nothing. 


Description 


Generates the square wave signal on the appropriate pin. 

Parameters: 

- freq in Hz: signal frequency in Hertz (Hz) 

-duration ms : signal duration in miliseconds (ms) 

Note: frequency range is limited by Delay_Cyc parameter. Maximum frequency 
that can be produced by this function is Freq max = fosc/ (80* 3) . Minimum fre- 
quency is Freq min = Fosc/ (80* 255) . Generated frequency may differ from the 
freq in hz parameter due to integer arithmetics. 


Requires 


In order to hear the sound, you need a piezo speaker (or other hardware) on des- 
ignated port. Also, you must call Soundjnit to prepare hardware for output before 
using this function. 


Example 


// Play sound of lKHz in duration of 100ms 
Sound_Play (1000, 100); 



Library Example 

The example is a simple demonstration of how to use the Sound Library for play- 
ing tones on a piezo speaker. 



void Tonel () { 

Sound Play(659, 250); // Frequency = 659Hz, duration = 250ms 
} 

void Tone2 () { 

Sound_Play (698, 250); // Frequency = 698Hz, duration = 250ms 
} 

void Tone 3 () { 

Sound_Play (784, 250); // Frequency = 784Hz, duration = 250ms 



void Melody () { 



Tonel ( 
Tonel ( 
Tonel ( 
Tonel ( 
Tonel ( 
Tone3 ( 



Tone2 ( 
Tone2 ( 
Tone2 ( 
Tone2 ( 
Tone2 ( 
Tone3 ( 



Tone3 ( 
Tone3 ( 
Tone3 ( 
Tone3 ( 
Tone3 ( 
Tone2 ( 



// Plays the melody "Yellow house" 
Tone 3 () ; 
Tone 3 () ; 



Tone 3 () ; 

Tone2 () ; Tonel () 
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} 

void ToneA() { 

Sound_Play( 880, 50); 
} 
void ToneCO { 

Sound_Play (1046, 50); 
} 
void ToneE ( ) { 

Sound_Play (1318, 50); 
} 

void Melody2 () { 
unsigned short i; 

for (i = 9; i > 0; i--) { 

ToneA(); ToneCO; ToneE (); 
} 
} 

void main ( ) { 

ANSEL = 0; // Configure AN pins as digital I/O 

ANSELH = 0; 

TRISB = 0xF8; // Configure RB7..RB3 as input 

TRISD = 0xF7; // Configure RD3 as output 

Sound_Init (SPORTD, 3); 
Sound_Play (1000, 1000); 

while (1) { 

if (Button (&PORTB, 7, 1, 1) ) // RB7 plays Tonel 

Tonel () ; 
while (PORTB s 0x80) ; // Wait for button to be released 

if (Button (SPORTB, 6, 1, 1) ) // RB6 plays Tone2 

Tone2 () ; 
while (PORTB s 0x40) ; // Wait for button to be released 

if (Button (SPORTB, 5, 1,1) ) // RB5 plays Tone3 

Tone3 () ; 
while (PORTB s 0x20) ; // Wait for button to be released 

if (Button (SPORTB, 4, 1, 1) ) // RB4 plays Melody2 

Melody2 () ; 
while (PORTB & 0x10) ; // Wait for button to be released 

if (Button (SPORTB, 3, 1,1) ) // RB3 plays Melody 

Melody () ; 
while (PORTB s 0x08) ; // Wait for button to be released 
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HW Connection 



J 



PIEZO 
SPEAKER 



vcc 



PORTB.B3 



1DK MOK 10K 10K 




Example of Sound Library sonnection 
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SPI LIBRARY 

SPI module is available with a number of PIC MCU models. mikroC PRO for PIC provides a 
library for initializing Slave mode and comfortable work with Master mode. PIC can easily com- 
municate with other devices via SPI: A/D converters, D/A converters, MAX7219, LTC1290, etc. 
You need PIC MCU with hardware integrated SPI (for example, PIC16F877). 

Note: Some PIC18 MCUs have multiple SPI modules. Switching between the SPI modules in the 
SPI library is done by the SPI_Set_Active function (SPI module has to be previously initialized). 

Note: In order to use the desired SPI library routine, simply change the number 1 in the prototype 
with the appropriate module number, i.e. SPI2_lnit(); 



Library Routines 

- SpMJnit 

- Spi1_lnit_Advanced 

- Spi1_Read 

- Spi1_Write 

- Spi_Set_Active 

Spijnit 



Prototype 


void SPI1 Init (void) ; 


Returns 


Nothing. 


Description 


This routine configures and enables SPI module with the following settings: 

- master mode 

- 8 bit data transfer 

- most significant bit sent first 

- serial clock low when idle 

- data sampled on leading edge 

- serial clock = fosc/4 


Requires 


You need PIC MCU with hardware integrated SPI. 


Example 


SPIl Init(); // Initialize the SPI module with default settings 
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Spi1_lnit_Advanced 



Prototype 



Returns 



Description 



Requires 



Example 



void SPIl_Init_Advanced (unsigned short master_slav, unsigned short 
data_sample, unsigned short clock_idle, unsigned short transmit_edge) ; 



Nothing. 



Configures and initializes SPI. SPMJnit or SPI1_lnit_Advanced needs to be 
called before using other functions of SPI Library. 

Parameters mode, data sample and clock idle configure the SPI module, 
and can have the following values: 



Description 


Predefined library const 


SPI work mode: 


Mastei 


clock = Fosc/4 


SPI MASTER OSC DIV4 


Mastei 


clock = Fosc/16 


SPI MASTER OSC DIV16 


Master clock = Fosc/64 


SPI MASTER OSC DIV64 


Master clock source TMR2 


SPI MASTER TMR2 


Slave select enabled 


SPI SLAVE SS ENABLE 


Slave select disabled 




Data sampling interval: 


Input data sampled in middle of interval 


SPI DATA SAMPLE MID- 
DLE 


Input data sampled at the end of interval 


SPI DATA SAMPLE END 


SPI clock idle state: 


Clock idle HIGH 


SPI CLK IDLE HIGH 


Clock idle LOW 


SPI CLK IDLE LOW 


Transmit edge: 




SPI LOW 2 HIGH 


)ata transmit on high to 





You need PIC MCU with hardware integrated SPI. 



// Set SPI1 module to master mode, clock = Fosc/4, data sampled 
at the middle of interval, clock idle state low and data trans- 
mitted at low to high edge: 

SPIl_Init_Advanced (_SPI_MASTER_0SC_DIV4, _SPI_DATA_SAMPLE_MIDDLE, 
SPI CLK IDLE LOW, SPI LOW 2 HIGH); 
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Spi1_Read 



Prototype 


unsigned short SPI1 Read (unsigned short buffer); 


Returns 


Returns the received data. 


Description 


Reads one byte from the SPI bus. 

Parameters: 

- buffer: dummy data for clock generation (see device Datasheet for SPI 
modules implementation details) 


Requires 


You need PIC MCU with hardware integrated SPI. 

SPI must be initialized and communication established before using this func- 
tion. See SPI1_lnit_Advanced or SPMJnit. 


Example 


short take, buffer; 

take = SPI1 Read(buffer) ; 



Spi1_Write 



Prototype 


void SPI1 Write (unsigned short data ); 


Returns 


Nothing. 


Description 


Writes byte via the SPI bus. 

Parameters: 

- wrdata : data to be sent 


Requires 


You need PIC MCU with hardware integrated SPI. 

SPI must be initialized and communication established before using this func- 
tion. See SPI1_lnit_Advanced or SPMJnit. 


Example 


SPIl Write (1) ; 
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SPI Set Active 



Prototype 


void SPI Set Active (char (*read ptr) (char)) 


Returns 


Nothing. 


Description 


Sets the active SPI module which will be used by the SPI routines. 
Parameters: 

- read ptr: SPI1_Read handler 


Requires 


Routine is available only for MCUs with two SPI modules. 

Used SPI module must be initialized before using this function. See the 

SPMJnit, SPI1_lnit_Advanced 


Example 


SPI Set Active (&SPI2 Read); // Sets the SPI2 module active 



Library Example 

The code demonstrates how to use SPI library functions for communication between SPI module 
of the MCU and Microchip's MCP4921 12-bit D/A converter 

// DAC module connections 

sbit Chip_Select at RC0_bit; 

sbit Chip_Select_Direction at TRISCOJoit; 

// End DAC module connections 

unsigned int value; 



void InitMain() { 
TRISBOJoit = 1; 
TRISBl_bit = 1; 
Chip_Select = 1; 
Chip Select Direction 
SPI1 Init () ; 



// Set RAO pin as input 
// Set RA1 pin as input 
// Deselect DAC 
// Set CS# pin as Output 
// Initialize SPI module 



// DAC increments (0..4095) — > output voltage (O..Vref) 
void DAC_Output (unsigned int valueDAC) { 
char temp; 



Chip_Select 



0; 



// Select DAC chip 
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// Send High Byte 

temp = (valueDAC » 8) & OxOF; // Store valueDAC[ 11.. 8] to temp[ 3..0] 

temp |= 0x30; // Define DAC setting, see MCP4921 datasheet 

SPIl_Write (temp) ; // Send high byte via SPI 

// Send Low Byte 
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temp = valueDAC; 
SPIl_Write (temp) ; 

Chip_Select = 1; 



// Store valueDAC[ 7 . . 0] to temp[ 7 . . 0] 
// Send low byte via SPI 

// Deselect DAC chip 



void main ( ) { 
ANSEL = 0; 
ANSELH = 0; 
InitMain ( ) ; 



// Perform main initialization 



value 



2048; 



// When program starts, DAC gives 
// the output in the mid-range 



while (1) { 



// Endless loop 



if ((RAOJoit) && (value < 4095)) { // If RAO button is pressed 
value++; // increment value 

} 

else { 

if ((RAlJoit) SS (value > 0)) { //If RA1 button is pressed 
value--; // decrement value 



DAC_Output (value) ; 
Delay_ms (1 ) ; 



// Send value to DAC chip 
// Slow down key repeat pace 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 447 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



HW Connection 



B P a| All lines are disconnected 
B] Vrc-f line is con netted 




DAC 
CONNECTOR 



SPI HW connection 
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SPI ETHERNET LIBRARY 

The ENC28J60 is a stand-alone Ethernet controller with an industry standard Serial 
Peripheral Interface (SPI™). It is designed to serve as an Ethernet network interface 
for any controller equipped with SPI. 

The ENC28J60 meets all of the IEEE 802.3 specifications. It incorporates a number 
of packet filtering schemes to limit incoming packets. It also provides an internal 
DMA module for fast data throughput and hardware assisted IP checksum calcula- 
tions. Communication with the host controller is implemented via two interrupt pins 
and the SPI, with data rates of up to 10 Mb/s. Two dedicated pins are used for LED 
link and network activity indication. 

This library is designed to simplify handling of the underlying hardware (enc28j60). 
It works with any PIC with integrated SPI and more than 4 Kb ROM memory. 38 to 
40 MHz clock is recommended to get from 8 to 10 Mhz SPI clock, otherwise PIC 
should be clocked by enc28 J60 clock output due to its silicon bug in SPI hardware. 
If you try lower PIC clock speed, there might be board hang or miss some requests. 

SPI Ethernet library supports: 

- IPv4 protocol. 

- ARP requests. 

- ICMP echo requests. 

- UDP requests. 

- TCP requests (no stack, no packet reconstruction). 

- ARP client with cache. 

- DNS client. 

- UDP client. 

- DHCP client. 

- packet fragmentation is NOT supported. 

Note: Due to PIC1 6 RAM/Flash limitations PIC1 6 library does NOT have ARP, DNS, 
UDP and DHCP client support implemented. 

Note: Global library variable spiEthernetuserTimerSec is used to keep track of 
time for all client implementations (ARP, DNS, UDP and DHCP). It is user responsi- 
bility to increment this variable each second in it's code if any of the clients is used. 

Note: For advanced users there are header files ("eth enc28j60LibDef.h" and 
"eth_enc28j60LibPrivate.h") in Uses\P16 and Uses\P18 folders of the compiler 
with description of all routines and global variables, relevant to the user, implement- 
ed in the SPI Ethernet Library. 
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Note: The appropriate hardware SPI module must be initialized before using any of 
the SPI Ethernet library routines. Refer to SPI Library. 

For MCUs with two SPI modules it is possible to initialize both of them and then 
switch by using the spisetActive o routine. 



External dependencies of SPI Ethernet Library 



The following variables 
must be defined in all 
projects using SPI Eth- 
ernet Library: 


Description: 


Example: 


extern sfr sbit 

SPI Ethernet CS 


ENC28J60 chip select pin. 


at RC1 bit; 


extern sfr sbit 

SPI Ethernet RST; 


ENC28J60 reset pin. 


at RCO bit; 


extern sfr sbit 

SPI Ethernet CS Direc 
tion; 


Direction of the ENC28J60 
chip select pin. 


sbit 

SPI Ethernet CS Direc 
tion at TRISC1 bit; 


extern sfr sbit 

SPI Ethernet RST Dire 
ction; 


Direction of the ENC28J60 
reset pin. 


sbit 

SPI Ethernet Rst Dire 
ction at TRISCO bit; 



The following routines must be 

defined in all project using SPI 

Ethernet Library: 


Description: 


Example: 


unsigned int 

SPI Ethernet UserTCP (unsigned 
char *remoteHost, unsigned 
int remotePort, unsigned int 
localPort, unsigned int 

reqLength) ; 


TCP request handler. 


Refer to the library 
example at the bot- 
tom of this page for 
code implementa- 
tion. 


unsigned int 

SPI Ethernet UserUDP (unsigned 
char *remoteHost, unsigned int 
remotePort, unsigned int 
destPort, unsigned int 

reqLength) ; 


UDP request handler. 


Refer to the library 
example at the bot- 
tom of this page for 
code implementa- 
tion. 
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Library Routines 
PIC16and PIC18: 

- SPI_Ethernet_lnit 

- SPI_Ethernet_Enable 

- SPI_Ethernet_Disable 

- SPIEthemetdoPacket 

- SPIEthemetputByte 

- SPI_Ethemet_putBytes 

- SPI_Ethernet_putString 

- SPI_Ethernet_putConstString 

- SPI_Ethernet_putConstBytes 

- SPI_Ethemet_getByte 

- SPI_Ethemet_getBytes 

- SPI_Ethernet_UserTCP 

- SPI_Ethernet_UserUDP 

PIC18 0nly: 

- SPIEthemetgetlpAddress 

- SPI_Ethernet_getGwlpAddress 

- SPIEthemetgetDnslpAddress 

- SPI_Ethernet_getlpMask 

- SPI_Ethernet_confNetwork 

- SPI_Ethernet_arpResolve 

- SPIEthemetsendUDP 

- SPIEthemetdnsResolve 

- SPI_Ethernet_initDHCP 

- SPI_Ethemet_doDHCPLeaseTime 

- SPI Ethernet renewDHCP 
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Spi_Ethernet_lnit 



Prototype 



Returns 



Description 



void SPI_Ethernet_Init (unsigned char 
unsigned char fullDuplex) ; 



mac, unsigned char *ip, 



Nothing. 



This is MAC module routine. It initializes enc28jgo controller. This function is 
internaly splited into 2 parts to help linker when coming short of memory. 

ENC2 8J60 controller settings (parameters not mentioned here are set to default): 

- receive buffer start address : Oxoooo. 

- receive buffer end address : 0x19ad. 

- transmit buffer start address: 0x19ae. 

- transmit buffer end address : Oxifff. 

- RAM buffer read/write pointers in auto-increment mode. 

- receive filters set to default: CRC + MAC Unicast + MAC Broadcast in OR mode. 

- flow control with TX and RX pause frames in full duplex mode. 

- frames are padded to 60 bytes + CRC. 

- maximum packet size is set to 151 8. 

- Back-to-Back Inter-Packet Gap: 0x15 in full duplex mode; 0x12 in half duplex mode. 

- Non-Back-to-Back Inter-Packet Gap: 0x0012 in full duplex mode; 0x0ci2 in 
half duplex mode. 

- Collision window is set to 63 in half duplex mode to accomodate some - 
ENC28J60 revisions silicon bugs. 

- CLKOUT output is disabled to reduce EMI generation. 

- half duplex loopback disabled. 

- LED configuration: default (LEDA-link status, LEDB-link activity). 

Parameters: 

- mac: RAM buffer containing valid MAC address. 

- ip: RAM buffer containing valid IP address. 



- fullDuplex: ethernet duplex mode switch. Valid values: 
and 1 (full duplex mode). 



(half duplex mode) 
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Global variables: 

SPiEthernetcs: Chip Select line 

SPiEthernetcsDirection: Direction of the Chip Select pin 
SPi_Ethernet_RST: Reset line 
SPiEthernetRSTDirection: Direction of the Reset pin 

must be defined before using this function. 

The SPI module needs to be initialized. See the SPHInit and 
SPI1 Init Advanced routines. 



#define SPI_Ethernet_HALFDUPLEX 
fdefine SPI_Ethernet_FULLDUPLEX 1 

// mE ehternet NIC pinout 

sfr sbit SPI_Ethernet_Rst at RCOJoit; 

sfr sbit SPI_Ethernet_CS at RClJoit; 

sfr sbit SPI_Ethernet_Rst_Direction at TRISCOJoit; 

sfr sbit SPI_Ethernet_CS_Direction at TRISCl_bit; 

// end ethernet NIC definitions 



unsigned char myMacAddr[ 6] 
0x3f} ; // my MAC address 
unsigned char mylpAddr 
addr 



{ 0x00, 0x14, 0xA5, 0x76, 0x19, 
{ 192, 168, 1, 60 } ; // my IP 



SPIl_Init () ; 

SPI_Ethernet_Init (myMacAddr, mylpAddr, SPI_Ethernet_FULLDUPLEX) ; 
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Spi_Ethernet_Enable 



Prototype 



Returns 



Description 



void SPI_Ethernet_Enable (unsigned char enFlt) ; 



Nothing. 



This is MAC module routine. This routine enables appropriate network traffic on 
the ENC2 8J60 module by the means of it's receive filters (unicast, multicast, 
broadcast, crc). Specific type of network traffic will be enabled if a corresponding 
bit of this routine's input parameter is set. Therefore, more than one type of net- 
work traffic can be enabled at the same time. For this purpose, predefined library 
constants (see the table below) can be ORed to form appropriate input value. 

Parameters: 

- enFit : network traffic/receive filter flags. Each bit corresponds to the appropri- 
ate network traffic/receive filter: 



Bit 


Mask 


Description 


Predefined library const 





0x01 


MAC Broadcast traffic/receive filter 
flag. When set, MAC broadcast traf- 
fic will be enabled. 


SPI Ethernet BROAD- 
CAST 


1 


0x02 


MAC Multicast traffic/receive filter 
flag. When set, MAC multicast traffic 
will be enabled. 


SPI Ethernet MULTI- 
CAST 


2 


0x04 


not used 


none 


3 


0x08 


not used 


none 


4 


0x10 


not used 


none 


5 


0x20 


CRC check flag. When set, packets 
with invalid CRC field will be discarded. 


SPI Ethernet CRC 


6 


0x40 


not used 


none 


7 


0x80 


MAC Unicast traffic/receive filter flag. 
When set, MAC unicast traffic will be 
enabled. 


SPI Ethernet UNICAST 



Note: Advance filtering available in the enc28 j60 module such as Pattern 
Match, Magic Packet and Hash Table can not be enabled by this routine. 
Additionaly, all filters, except CRC, enabled with this routine will work in OR mode, 
which means that packet will be received if any of the enabled filters accepts it. 

Note: This routine will change receive filter configuration on-the-fly. It will not, in 
any way, mess with enabling/disabling receive/transmit logic or any other part of 
the ENC28J60 module. The ENC28J60 module should be properly cofigured by 
the means of SPI Ethernet Init routine. 
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Ethernet module has to be initialized. See SPI Ethernet Init. 



SPI_Ethernet_Enable (_SPI_Ethernet_CRC I _SPI_Ethernet_UNICAST) 
// enable CRC checking and Unicast traffic 



Spi_Ethernet_Disable 



Prototype 



Returns 



Description 



void SPI_Ethernet_Disable (unsigned char disFlt); 



Nothing. 



This is MAC module routine. This routine disables appropriate network traffic on 
the ENC2 8J60 module by the means of it's receive filters (unicast, multicast, 
broadcast, crc). Specific type of network traffic will be disabled if a corresponding 
bit of this routine's input parameter is set. Therefore, more than one type of net- 
work traffic can be disabled at the same time. For this purpose, predefined library 
constants (see the table below) can be ORed to form appropriate input value. 

Parameters: 

- disFlt: network traffic/receive filter flags. Each bit corresponds to the appro- 
priate network traffic/receive filter: 



Bit 



Mask 



0x01 



0x02 



0x04 



0x08 



0x10 



0x20 



0x40 



0x80 



Description 



MAC Broadcast traffic/receive filter flag. When 
set, MAC broadcast traffic will be disabled. 



MAC Multicast traffic/receive filter flag. When 
set, MAC multicast traffic will be disabled. 



not used 



not used 



not used 



CRC check flag. When set, CRC check wil 
be disabled and packets with invalid CRC 
field will be accepted. 



not used 



MAC Unicast traffic/receive filter flag. When 
set, MAC unicast traffic will be disabled. 



Predefined library 
const 



Spi_Ethernet_BRO 
ADCAST 



Spi_Ethernet_MUL 
TICAST 



Spi_Ethernet_CRC 



Spi_Ethernet_UNI 
CAST 



Note: Advance filtering available in the enc28j60 module such as Pattern 

Match, Magic Packet and Hash Table can not be disabled by this routine. 

Note: This routine will change receive filter configuration on-the-fly. It will not, in 
any way, mess with enabling/disabling receive/transmit logic or any other part of 
the ENC28J60 module. The ENC28J60 module should be properly cofigured by 
the means of SPI Ethernet Init routine. 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 455 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



Requires 



Example 



Ethernet module has to be initialized. See SPI Ethernet Init. 



SPI_Ethernet_Disable (_SPI_Ethernet_CRC I _SPI_Ethernet_UNICAST) 
// disable CRC checking and Unicast traffic 



Spi_Ethernet_doPacket 



Prototype 


unsigned char SPI Ethernet doPacket (); 


Returns 


- o - upon successful packet processing (zero packets received or received 
packet processed successfully). 

- i - upon reception error or receive buffer corruption. enc28j60 controller 
needs to be restarted. 

- 2 - received packet was not sent to us (not our IP, nor IP broadcast address). 

- 3 - received IP packet was not IPv4. 

- 4 - received packet was of type unknown to the library. 


Description 


This is MAC module routine. It processes next received packet if such exists. 
Packets are processed in the following manner: 

- ARP & ICMP requests are replied automatically. 

- upon TCP request the Spi_Ethemet_UserTCP function is called for further 
processing. 

- upon UDP request the Spi_Ethernet_UserUDP function is called for further 
processing. 

Note: spi Ethernet doPacket must be called as often as possible in user's code. 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


if (SPI Ethernet doPacket () == 0) (1) { // process received pack- 
ets 

] 
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Spi_Ethernet_putByte 



Prototype 


void SPI Ethernet putByte (unsigned char v) ; 


Returns 


Nothing. 


Description 


This is MAC module routine. It stores one byte to address pointed by the cur- 
rent enc28 J60 write pointer (EWRPT). 

Parameters: 

- v: value to store 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


char data; 

SPI Ethernet putByte (data) ; // put an byte into ENC28 J60 buffer 



Spi_Ethernet_putBytes 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_Ethernet_putBytes (unsigned char *ptr, unsigned char n) ; 



Nothing. 



This is MAC module routine. It stores requested number of bytes into ENC28J60 
RAM starting from current enc2 8j60 write pointer (ewrpt) location. 

Parameters: 

- ptr : RAM buffer containing bytes to be written into enc28j60 RAM. 

- n : number of bytes to be written. 



Ethernet module has to be initialized. See SpiEthernetlnit. 



char * buffer 



"mikroElektronika" , 



SPI Ethernet putBytes (buffer, 16); // put an RAM array into 
ENC28J60 buffer 
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Spi_Ethernet_putConstBytes 



Prototype 


void SPI Ethernet putConstBytes (const unsigned char *ptr, unsigned 
char n) ; 


Returns 


Nothing. 


Description 


This is MAC module routine. It stores requested number of const bytes into 

ENC28J60 RAM starting from current enc28j60 write pointer (ewrpt) location. 

Parameters: 

- ptr : const buffer containing bytes to be written into ENC28J60 RAM. 

- n : number of bytes to be written. 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


const char *buffer = "mikroElektronika"; 

SPI Ethernet putConstBytes (buffer, 16); // put a const array into 
ENC28J60 buffer 



Spi_Ethernet_putString 



Prototype 



unsigned int SPI_Ethernet_putString (unsigned char *ptr) ; 



Returns 



Number of bytes written into enc28jgo RAM. 



Description 



This is MAC module routine. It stores whole string (excluding null termination) into 
ENC28J60 RAM starting from current enc28jgo write pointer (ewrpt) location. 

Parameters: 

- ptr : string to be written into enc28 j60 RAM. 



Requires 



Ethernet module has to be initialized. See SpiEthernetlnit. 



Example 



char * buffer 



'mikroElektronika" ; 



SPI_Ethernet_putString (buffer) ; // put a RAM string into ENC28J60 

buffer 
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Spi_Ethernet_putConstString 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned int SPI_Ethernet_putConstString (const unsigned char *ptr) ; 



Number of bytes written into enc28j60 RAM. 



This is MAC module routine. It stores whole const string (excluding null termination) 
into enc28 J60 RAM starting from current enc28j60 write pointer (ewrpt) location. 

Parameters: 

- ptr : const string to be written into enc28j60 RAM. 



Ethernet module has to be initialized. See SpiEthernetlnit. 



const char * buffer 



'mikroElektronika" ; 



SPI Ethernet putConstString (buf f er ) ; // put a const string into 
ENC28J60 buffer 



Spi_Ethernet_getByte 



Prototype 


unsigned char SPI Ethernet getByteO; 


Returns 


Byte read from ENC2 8J60 RAM. 


Description 


This is MAC module routine. It fetches a byte from address pointed to by cur- 
rent enc28 J60 read pointer (erdpt). 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


char buffer; 

buffer = SPI Ethernet getByteO; // read a byte from ENC28J60 
buffer 
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Spi_Ethernet_getBytes 



Prototype 


void SPI Ethernet getBytes (unsigned char *ptr, unsigned int addr, 
unsigned char n) ; 


Returns 


Nothing. 


Description 


This is MAC module routine. It fetches equested number of bytes from 
ENC28J60 RAM starting from given address. If value of Oxffff is passed as the 
address parameter, the reading will start from current enc28j60 read pointer 
(erdpt) location. 

Parameters: 

- ptr : buffer for storing bytes read from ENC28J60 RAM. 

- addr: ENC28J60 RAM start address. Valid values: o. .8192. 

- n : number of bytes to be read. 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


char buffer[ 16] ; 

SPI Ethernet getBytes (buff er, 0x100, 16); // read 16 bytes, 
starting from address 0x100 
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Prototype 


unsigned int SPI Ethernet UserTCP (unsigned char * remoteHost, 
unsigned int remotePort, unsigned int localPort, unsigned int 
reqLength) ; 


Returns 


- o - there should not be a reply to the request. 

- Length of TCP/HTTP reply data field - otherwise. 


Description 


This is TCP module routine. It is internally called by the library. The user access- 
es to the TCP/HTTP request by using some of the SPIEthernetget routines. 
The user puts data in the transmit buffer by using some of the SPI_Ethernet_put 
routines. The function must return the length in bytes of the TCP/HTTP reply or 
if there is nothing to transmit. If there is no need to reply to the TCP/HTTP 
requests, just define this function with return(O) as a single statement. 

Parameters: 

- remoteHost : client's IP address. 

- remotePort : client's TCP port. 

- localPort : port to which the request is sent. 

- reqLength : TCP/HTTP request data field length. 

Note: The function source code is provided with appropriate example projects. 
The code should be adjusted by the user to achieve desired reply. 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


This function is internally called by the library and should not be called by the 
user's code. 
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Spi_Ethernet_UserUDP 



Prototype 


unsigned int SPI Ethernet UserUDP (unsigned char * remoteHost, 
unsigned int remotePort , unsigned int destPort, unsigned int 

reqLength) ; 


Returns 


- o - there should not be a reply to the request. 

- Length of UDP reply data field - otherwise. 


Description 


This is UDP module routine. It is internally called by the library. The user access- 
es to the UDP request by using some of the SPI_Ethernet_get routines. The user 
puts data in the transmit buffer by using some of the SPI_Ethernet_put routines. 
The function must return the length in bytes of the UDP reply or if nothing to 
transmit. If you don't need to reply to the UDP requests, just define this function 
with a return(O) as single statement. 

Parameters: 

- remoteHost : client's IP address. 

- remotePort : client's port. 

- destPort : port to which the request is sent. 

- reqLength : UDP request data field length. 

Note: The function source code is provided with appropriate example projects. 
The code should be adjusted by the user to achieve desired reply. 


Requires 


Ethernet module has to be initialized. See SpiEthernetlnit. 


Example 


This function is internally called by the library and should not be called by the 
user's code. 



SPI_Ethernet_getlpAddress 



Prototype 


unsigned char * SPI Ethernet getlpAddress () ; 


Returns 


Ponter to the global variable holding IP address. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned IP address. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own IP address buffer. These locations should not be altered 
by the user in any case. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char ipAddr[ 4] ; // user IP address buffer 

memcpy (ipAddr, SPI Ethernet getlpAddress () , 4); // fetch IP address 
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SPI_Ethernet_getGwlpAddress 



Prototype 


unsigned char * SPI Ethernet getGwIpAddress () ; 


Returns 


Ponter to the global variable holding gateway IP address. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned gateway IP address. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own gateway IP address buffer. These locations should not be 
altered by the user in any case! 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char gwIpAddr[ 4] ; // user gateway IP address buffer 

memcpy (gwIpAddr, SPI Ethernet getGwIpAddress () , 4); // fetch gate- 
way IP address 



SPI_Ethernet_getDnslpAddress 



Prototype 


unsigned char * SPI Ethernet getDnsIpAddress () 


Returns 


Ponter to the global variable holding DNS IP address. 


Description 


This routine should be used when DHCP server is present on the network to fetch 
assigned DNS IP address. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own DNS IP address buffer. These locations should not be 
altered by the user in any case. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char dnsIpAddr[ 4] ; // user DNS IP address buffer 

memcpy (dnsIpAddr, SPI Ethernet getDnsIpAddress () , 4); // fetch 
DNS server address 
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SPI_Ethernet_getlpMask 



Prototype 


unsigned char * SPI Ethernet getlpMask () 


Returns 


Ponter to the global variable holding IP subnet mask. 


Description 


This routine should be used when DHCP server is present on the network to 
fetch assigned IP subnet mask. 

Note: User should always copy the IP address from the RAM location returned 
by this routine into it's own IP subnet mask buffer. These locations should not 
be altered by the user in any case. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char IpMask[ 4] ; // user IP subnet mask buffer 

memcpy (IpMask, SPI Ethernet getIpMask(), 4); // fetch IP subnet 
mask 



SPI Ethernet confNetwork 



Prototype 


void SPI Ethernet confNetwork (char * ipMask, char *gwIpAddr, char 
*dnsIpAddr) ; 


Returns 


Nothing. 


Description 


Configures network parameters (IP subnet mask, gateway IP address, DNS IP 
address) when DHCP is not used. 

Parameters: 

- ipMask: IP subnet mask. 

- gwipAddr gateway IP address. 

- dnsipAddr: DNS IP address. 

Note: The above mentioned network parameters should be set by this routine 
only if DHCP module is not used. Otherwise DHCP will override these settings 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


example : 255.255.255.0) 

char gwIpAddr[ 4] = { 192, 168, 1, 1 } ; // gateway (router) 

IP address 

char dnsIpAddr[ 4] = { 192, 168, 1, 1 } ; // DNS server IP 

address 

SPI Ethernet confNetwork (ipMask, gwipAddr, dnsipAddr) ; // set 
network configuration parameters 
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SPI_Ethernet_arpResolve 



Prototype 


unsigned char *SPI Ethernet arpRe solve (unsigned char *ip, unsigned 
char tmax) ; 


Returns 


- MAC address behind the IP address - the requested IP address was resolved. 

- o - otherwise. 


Description 


This is ARP module routine. It sends an ARP request for given IP address and 
waits for ARP reply. If the requested IP address was resolved, an ARP cash entry 
is used for storing the configuration. ARP cash can store up to 3 entries. For ARP 
cash structure refer to "eth enc28j60LibDef .h" header file in the compiler's 
Uses/P1 8 folder. 

Parameters: 

- ip: IP address to be resolved. 

- tmax : time in seconds to wait for an reply. 

Note: The Ethernet services are not stopped while this routine waits for ARP 
reply. The incoming packets will be processed normaly during this time. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char IpAddr[ 4] = { 192, 168, 1, 1 } ; // IP address 

SPI Ethernet arpResolve ( IpAddr , 5); // get MAC address behind the 
above IP address, wait 5 sees for the response 
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SPI Ethernet sendUDP 



Prototype 


unsigned char SPI Ethernet sendUDP (unsigned char *destIP, unsigned 
int sourcePort, unsigned int destPort, unsigned char *pkt, unsigned 

int pktLen) ; 


Returns 


- 1 - UDP packet was sent successfuly. 
- o - otherwise. 


Description 


This is UDP module routine. It sends an UDP packet on the network. 
Parameters: 

- destip: remote host IP address. 

- sourcePort: local UDP source port number. 

- destPort: destination UDP port number. 

- pkt: packet to transmit. 

- pktLen: length in bytes of packet to transmit. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char IpAddr[ 4] = { 192, 168, 1, 1 } ; // remote IP 
address 

SPI Ethernet sendUDP (IpAddr, 10001, 10001, "Hello", 5); // send 
Hello message to the above IP address, from UDP port 10001 to 
UDP port 10001 
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SPI Ethernet dnsResolve 



Prototype 


unsigned char * SPI Ethernet dnsResolve (unsigned char *host, 
unsigned char tmax) ; 


Returns 


- pointer to the location holding the IP address - the requested host name was 
resolved. 

- o - otherwise. 


Description 


This is DNS module routine. It sends an DNS request for given host name and 
waits for DNS reply. If the requested host name was resolved, it's IP address is 
stored in library global variable and a pointer containing this address is returned 
by the routine. UDP port 53 is used as DNS port. 

Parameters: 

-host: host name to be resolved. 

-tmax: time in seconds to wait for an reply. 

Note: The Ethernet services are not stopped while this routine waits for DNS 
reply. The incoming packets will be processed normaly during this time. 

Note: User should always copy the IP address from the RAM location returned by 
this routine into it's own resolved host IP address buffer. These locations should 
not be altered by the user in any case. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


unsigned char * remoteHostIpAddr[ 4] ; // user host IP address 
buffer 

// SNTP server: 

// Zurich, Switzerland: Integrated Systems Lab, Swiss Fed. Inst. 

of Technology 

// 129.132.2.21: swisstime . ethz . ch 

// Service Area: Switzerland and Europe 

memcpy (remoteHostlpAddr, 

SPI Ethernet dnsResolve ( "swisstime . ethz . ch" , 5), 4); 
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SPI Ethernet initDHCP 



Prototype 


unsigned char SPI Ethernet initDHCP (unsigned char tmax); 


Returns 


- : - network parameters were obtained successfully. 

- o - otherwise. 


Description 


This is DHCP module routine. It sends an DHCP request for network parameters 
(IP, gateway, DNS addresses and IP subnet mask) and waits for DHCP reply. If 
the requested parameters were obtained successfuly, their values are stored into 
the library global variables. 

These parameters can be fetched by using appropriate library IP get routines: 

- SPIEthernetgetlpAddress - fetch IP address. 

- SPIEthernetgetGwIpAddress - fetch gateway IP address. 

- SPIEthernetgetDnslpAddress - fetch DNS IP address. 

- SPIEthernetgetlpMask - fetch IP subnet mask. 

UDP port 68 is used as DHCP client port and UDP port 67 is used as DHCP serv- 
er port. 

Parameters: 

- tmax: time in seconds to wait for an reply. 

Note: The Ethernet services are not stopped while this routine waits for DNS 
reply. The incoming packets will be processed normaly during this time. 

Note: When DHCP module is used, global library variable 
spi Ethernet usenimerSec is used to keep track of time. It is user responsi- 
bility to increment this variable each second in it's code. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


SPI Ethernet initDHCP ( 5) ; // get network configuration from DHCP 
server, wait 5 sec for the response 
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SPI Ethernet doDHCPLeaseTime 



Prototype 


unsigned char SPI Ethernet doDHCPLeaseTime () ; 


Returns 


- o - lease time has not expired yet. 

- : - lease time has expired, it's time to renew it. 


Description 


This is DHCP module routine. It takes care of IP address lease time by decre- 
menting the global lease time library counter. When this time expires, it's time to 
contact DHCP server and renew the lease. 


Requires 


Ethernet module has to be initialized. See SPI_Ethemet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


if (SPI Ethernet doDHCPLeaseTime () ) 

... // it's time to renew the IP address lease 
} 



SPI Ethernet renewDHCP 



Prototype 


unsigned char SPI Ethernet renewDHCP (unsigned char tmax) ; 


Returns 


- 1 - upon success (lease time was renewed). 
- o - otherwise (renewal request timed out). 


Description 


This is DHCP module routine. It sends IP address lease time renewal request to 
DHCP server. 

Parameters: 

- tmax: time in seconds to wait for an reply. 


Requires 


Ethernet module has to be initialized. See SPI_Ethernet_lnit. 
Available for PIC1 8 family MCUs only. 


Example 


while (1) { 

if (SPI Ethernet doDHCPLeaseTime () ) 

SPI Ethernet renewDHCP (5 ) ; // it's time to renew the IP 
address lease, with 5 sees for a reply 

} 
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Library Example 

This code shows how to use the Ethernet mini library : 

- the board will reply to ARP & ICMP echo requests 

- the board will reply to UDP requests on any port : 

returns the request in upper char with a header made of remote host IP & 
port number 

- the board will reply to HTTP requests on port 80, GET method with pathnames : 

/ will return the HTML main page 

/s will return board status as text string 

/to ... IU will toggle RDO to RD7 bit and return HTML main page 

all other requests return also HTML main page. 



// duplex config flags 

#define Spi_Ethernet_HALFDUPLEX 

#define Spi_Ethernet_FULLDUPLEX 



0x00 // half duplex 
0x01 // full duplex 



// mE ehternet NIC pinout 

sfr sbit SPI_Ethernet_Rst at RCOJoit; 

sfr sbit SPI_Ethernet_CS at RCl_bit; 

sfr sbit SPI_Ethernet_Rst_Direction at TRISCOJoit; 

sfr sbit SPI_Ethernet_CS_Direction at TRISCl_bit; 

// end ethernet NIC definitions 



* ROM constant strings 
*/ 

const unsigned char httpHeader[ ] = "HTTP/1.1 200 OKnContent-type : " 

// HTTP header 
const unsigned char httpMimeTypeHTML[ ] = "text/htmlnn" ; 
// HTML MIME type 

const unsigned char httpMimeTypeScript[ ] = "text/plainnn" ; 
// TEXT MIME type 

unsigned char httpMethod[ ] = "GET /"; 
/* 

* web page, splited into 2 parts : 

* when coming short of ROM, fragmented data is handled more effi- 
ciently by linker 

* this HTML page calls the boards to get its status, and builds 
itself with javascript 

*/ 

const char * indexPage = // Change the IP address of the page to 
be refreshed 

"<meta http-equiv=" re fresh" con tent =" 3; url=http ://192.168.20.60"> 
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<HTMLXHEADX/HEADXBODY> 

<hl>PIC + ENC28J60 Mini Web Server</hl> 

<a href=/>Reload</a> 

<script src=/s></script> 

<tablextrxtd valign=top><table border=l style = "f ont-size : 20px 

; font- family : terminal ; "> 

<tr><th colspan=2>ADC</thX/tr> 

<trXtd>AN2</tdXtdXscript> document .write (AN2 )< /scrip tx/tdx/tr> 

< t rx t d> AN 3</tdxtd><script> document .write (AN3)< /scrip tx/tdx/tr> 

</table></tdxtdxtable border=l style="f ont-size : 20px ; font-family : 

terminal ; "> 

<tr><th colspan=2>P0RTB</thX/tr> 

<script> 

var str,i; 

str="" ; 

for (i=0;i<8;i++) 

{ str+="<trxtd bgcolor=pink>BUTTON #"+i + "</td> " ; 

if (PORTB& (l«i) ){ str+="<td bgcolor=red>ON" ;} 

else { str+="<td bgcolor=#cccccc>OFF" ;} 

str+="</tdX/tr>";} 

document .write (str) ; 

</script> 

const char * indexPage2 = "</table></tdxtd> 

<table border=l style="f ont-size : 20px ; font-family : terminal ; "> 

<tr><th colspan=3>P0RTD</thX/tr> 

<script> 

var str,i; 

str=""; 

for (i=0;i<8;i++) 

{ str+="<trxtd bgcolor=yellow>LED # " + i + "</td> " ; 

if (PORTDS (l«i) ){ str+="<td bgcolor=red>ON" ;} 

else { str+="<td bgcolor=#cccccc>OFF" ;} 

str+="</tdxtd><a href=/t" + i + ">Toggle</a></tdx/tr> " ;} 

document .write (str) ; 

</script> 

</table></tdx/trX/table> 

This is HTTP request 

#<script>document. write (REQ) </script></BODYX/HTML> 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* RAM variables 

*/ 
unsigned char myMacAddr[ 6] = { 0x00, 0x14, 0xA5, 0x76, 0x19, 0x3f} ; 
// my MAC address 

unsigned char myIpAddr[ 4] = { 192, 168, 20, 60} ; 
// my IP address 
unsigned char getRequest[ 15] ; // HTTP request buffer 
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unsigned char dyna[ 30] ; // buffer for dynamic response 
unsigned long httpCounter =0; // counter of HTTP requests 

/* ****************************************** 

* functions 
*/ 

/* 

* put the constant string pointed to by s to the ENC transmit buffer. 
*/ 

/*unsigned int putConstString (const char *s) 
{ 



unsigned int ctr = 0; 
wh i 1 e ( * s ) 



{ 

Spi_Ethernet_putByte (*s++) ; 
ctr++; 
} 
return (ctr) ; 
}*/ 
/* 

* it will be much faster to use library Spi Ethernet putConstString 
routine 

* instead of putConstString routine above. However, the code will 
be a little 

* bit bigger. User should choose between size and speed and pick the 
implementation that 

* suites him best. If you choose to go with the putConstString def- 
inition above 

* the #define line below should be commented out. 
* 

*/ 

#define putConstString SPI Ethernet putConstString 

/* 

* put the string pointed to by s to the ENC transmit buffer 
*/ 

/♦unsigned int putString (char *s) 
{ 
unsigned int ctr = ; 

while (* s ) 
{ 
Spi_Ethernet_putByte (*s++) ; 

ctr++; 



return (ctr) 
}*/ 
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/* 

* it will be much faster to use library Spi Ethernet putString rou- 
tine 

* instead of putString routine above. However, the code will be a 
little 

* bit bigger. User should choose between size and speed and pick the 
implementation that 

* suites him best. If you choose to go with the putString defini- 
tion above 

* the tdefine line below should be commented out. 
* 

*/ 

#define putString SPI Ethernet putString 

/* 

* this function is called by the library 

* the user accesses to the HTTP request by successive calls to 
Spi_Ethernet_getByte () 

* the user puts data in the transmit buffer by successive calls to 
Spi_Ethernet_putByte () 

* the function must return the length in bytes of the HTTP reply, 
or if nothing to transmit 

■k 

* if you don't need to reply to HTTP requests, 

* just define this function with a return (0) as single statement 

*/ 
unsigned int SPI_Ethernet_UserTCP (unsigned char *remoteHost, 
unsigned int remotePort, unsigned int localPort, unsigned int 

reqLength) 
{ 

unsigned int len =0; // my reply length 
unsigned int i; // general purpose integer 

if (localPort != 80) //I listen only to web request on port 80 
{ 

return ( ) ; 
} 

// get 10 first bytes only of the request, the rest does not 
matter here 

for(i = 0; i < 10; i++) 
{ 

getRequest[ i] = SPI_Ethernet_getByte ( ) ; 
} 
getRequest[ i] = ; 

if (memcmp (getRequest, httpMethod, 5)) // only GET 
method is supported here 
{ 
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return ( ) ; 

} 

httpCounter++; // one more request done 

if (getRequest[ 5] == ' s ' ) //if request path name starts 
with s, store dynamic data in transmit buffer 
{ 

// the text string replied by this request can be 
interpreted as javascript statements 
// by browsers 

len = putConstString (httpHeader) ; // HTTP header 
len += putConstString (httpMimeTypeScript ) ; // with 
text MIME type 

// add AN2 value to reply 

IntToStr (ADC_Read (2) , dyna); 

len += putConstString ( "var AN2="); 

len += putString (dyna) ; 

len += putConstString (";") ; 

// add AN3 value to reply 

IntToStr (ADC_Read (3) , dyna); 

len += putConstString ( "var AN3="); 

len += putString (dyna) ; 

len += putConstString (";") ; 

// add PORTB value (buttons) to reply 
len += putConstString ("var PORTB="); 
IntToStr (PORTB, dyna); 
len += putString (dyna) ; 
len += putConstString (";") ; 

// add PORTD value (LEDs) to reply 
len += putConstString ("var PORTD="); 
IntToStr (PORTD, dyna); 
len += putString (dyna) ; 
len += putConstString (";") ; 

// add HTTP requests counter to reply 
IntToStr (httpCounter, dyna); 
len += putConstString ( "var REQ="); 
len += putString (dyna) ; 
len += putConstString (";") ; 
} 
else if (getRequest[ 5] == ' t ' ) //if request path name starts 
with t, toggle PORTD (LED) bit number that comes after 
{ 
unsigned char bitMask =0; // for bit mask 
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if (isdigit (getRequest[ 6] ) ) // if <= bit number 
<= 9, bits 8 S 9 does not exist but does not matter 

{ 
bitMask = getRequest[ 6] - '0'; // convert 



ASCII to integer 

operator 

} 



bitMask = 1 << bitMask; // create bit mask 
PORTD A = bitMask; // toggle PORTD with xor 



} 



if (len == 0) // what do to by default 

{ 

len = putConstString (httpHeader) ; // HTTP header 
len += putConstString (httpMimeTypeHTML) ; // with 
HTML MIME type 

len += putConstString (indexPage ) ; // HTML page first 
part 

len += putConstString (indexPage2 ) ; // HTML page sec- 
ond part 

} 

return (len); // return to the library with the number of 
bytes to transmit 
} 

/* 

* this function is called by the library 

* the user accesses to the UDP request by successive calls to 
Spi_Ethernet_getByte () 

* the user puts data in the transmit buffer by successive calls to 
Spi_Ethernet_putByte () 

* the function must return the length in bytes of the UDP reply, or 
if nothing to transmit 

■k 

* if you don't need to reply to UDP requests, 

* just define this function with a return (0) as single statement 
* 

*/ 
unsigned int SPI_Ethernet_UserUDP (unsigned char *remoteHost, 
unsigned int remotePort, unsigned int destPort, unsigned int 

reqLength) 

{ 

unsigned int len; // my reply length 

unsigned char *ptr; // pointer to the dynamic buffer 

// reply is made of the remote host IP address in human read- 
able format 

ByteToStr (remoteHost[ 0] , dyna); // first IP address byte 
dyna[ 3] = ' . ' ; 
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ByteToStr (remoteHost[ 1] , dyna + 4); // second 

dyna[ 7] = 

ByteToStr (remoteHostf 2] , dyna + 8); // third 

dyna[ 11] = ' . '; 

ByteToStr (remoteHost[ 3] , dyna + 12); // fourth 



// add separator 



dyna[ 15] = ' : ' ; 

// then remote host port number 

WordToStr (remotePort, dyna + 16); 

dyna[ 21] = '[ '; 

WordToStr (destPort, dyna + 22); 

dyna[ 2 7] = '] ' ; 

dyna[ 2 8] = 0; 



// the total length of the request is the length of the 
dynamic string plus the text of the request 
len = 28 + reqLength; 

// puts the dynamic string into the transmit buffer 
SPI_Ethernet_putBytes (dyna, 28) ; 

// then puts the request string converted into upper char 
into the transmit buffer 

while (reqLength--) 
{ 
SPI_Ethernet_putByte (toupper (SPI_Ethernet_getByte () ) ) ; 



return (len); // back to the library with the length of the 



UDP reply 



/* 

* main entry 

*/ 
void main ( ) 
{ 



ANSEL = OxOC; 

PORTA = 0; 

TRISA = Oxff; 

ANSELH = 0; 

PORTB = 0; 

TRISB = Oxff; 

PORTD = 0; 

TRISD = 0; 

/* 



// AN2 and AN3 convertors will be used 

// set PORTA as input for ADC 

// Configure other AN pins as digital I/O 

// set PORTB as input for buttons 

// set PORTD as output 



476 MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



CHAPTER 7 
mikroC PRO for PIC Libraries 

* starts ENC28J60 with : 

* reset bit on RCO 

* CS bit on RC1 

* my MAC & IP address 

* full duplex 
*/ 

SPIl_Init () ; 

SPI_Ethernet_Init (myMacAddr, mylpAddr, Spi_Ethernet_FULLDU- 
PLEX) ; 

while (1) // do forever 

{ 
/* 
* if necessary, test the return value to get error code 
*/ 

SPI Ethernet doPacket ( ) ; // process incoming 
Ethernet packets 

/* 

* add your stuff here if needed 

* Spi Ethernet doPacket ( ) must be called as often as possible 

* otherwise packets could be lost 
*/ 

} 
} 
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SPI GRAPHIC LCD LIBRARY 

The mikroC PRO for PIC provides a library for operating Graphic Led 128x64 (with 
commonly used Samsung KS108/KS107 controller) via SPI interface. 

For creating a custom set of Glcd images use Glcd Bitmap Editor Tool. 

Note: The library uses the SPI module for communication. User must initialize SPI 
module before using the SPI Graphic Led Library. 

For MCUs with two SPI modules it is possible to initialize both of them and then 
switch by using the spiSetActive ( ) routine. 

Note: This Library is designed to work with the mikroElektronika's Serial Lcd/Glcd 
Adapter Board pinout, see schematic at the bottom of this page for details. 

External dependencies of SPI Graphic LCD Library 

The implementation of SPI Graphic Led Library routines is based on Port Expander 
Library routines. 

External dependencies are the same as Port Expander Library external dependen- 
cies. 

Library Routines 

Basic routines: 

- SPI_Glcd_lnit 

- SPI_Glcd_Set_Side 

- SPI_Glcd_Set_Page 

- SPI_Glcd_Set_X 

- SPI_Glcd_Read_Data 

- SPI_Glcd_Write_Data 

Advanced routines: 

- SPI_Glcd_Fill 

- SPI_Glcd_Dot 

- SPI_Glcd_Line 

- SPI_Glcd_V_Line 

- SPI_GlcdJH_Line 

- SPI_Glcd_Rectangle 

- SPI_Glcd_Box 

- SPI_Glcd_Circle 
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- SPI_Glcd_Set_Font 

- SPI_Glcd_Write_Char 

- SPI_Glcd_Write_Text 

- SPIGIcdlmage 

Spi_Glcd_lnit 



Prototype 


void SPI Glcd Init (char DeviceAddress); 


Returns 


Nothing. 


Description 


Initializes the GLCD module via SPI interface. 

Parameters: 

- DeviceAddress : spi expander hardware address, see schematic at the 
bottom of this page 


Requires 


Global variables: 

- sPExpandercs: Chip Select line 

- SPExpanderRST: Reset line 

- SPExpandercs Direction: Direction of the Chip Select pin 

- SPExpanderRST Direction: Direction of the Reset pin 

must be defined before using this function. 

The SPI module needs to be initialized. See SPMJnit and SPI1_lnit_Advanced 
routines. 


Example 


// Port Expander module connections 

sbit SPExpanderRST at RCO bit; 

sbit SPExpanderCS at RC1 bit; 

sbit SPExpanderRST Direction at TRISCO bit; 

sbit SPExpanderCS Direction at TRISC1 bit; 

// End Port Expander module connections 

// If Port Expander Library uses SPI module : 

SPI1 Init(); // Initialize SPI module used with PortExpander 

SPI Glcd Init (0) ; 
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SPI Glcd Set Side 



Prototype 


void SPI Glcd Set Side (char x pos; 


Returns 


Nothing. 


Description 


Selects Glcd side. Refer to the Glcd datasheet for detail explanation. 

Parameters: 

- x pos: position on x-axis. Valid values: 0..127 

The parameter x pos specifies the Glcd side: values from to 63 specify the 
left side, values from 64 to 127 specify the right side. 

Note: For side, x axis and page layout explanation see schematic at the bottom 
of this page. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


The following two lines are equivalent, and both of them select the left side of 
Glcd: 

SPI Glcd Set Side (0) ; 
SPI Glcd Set Side (10) ; 



SPI_Glcd_Set_Page 



Prototype 


void SPI Glcd Set Page (char page) ; 


Returns 


Nothing. 




Selects page of Glcd. 




Parameters: 


Description 


- page: page number. Valid values: 0..7 




Note: For side, x axis and page layout explanation see schematic at the bottom 




of this page. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


SPI Glcd Set Page (5) ; 
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SPI Glcd Set X 



Prototype 


void SPI Glcd Set X(char x pos); 


Returns 


Nothing. 


Description 


Sets x-axis position to x pos dots from the left border of Glcd within the select- 
ed side. 

Parameters: 

- x pos: position on x-axis. Valid values: 0..63 

Note: For side, x axis and page layout explanation see schematic at the bottom 
of this page. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


SPI Glcd Set X (25) ; 



Spi_Glcd_Read_Data 



Prototype 


char SPI Glcd Read Data ( ) ; 


Returns 


One byte from Glcd memory. 


Description 


Reads data from the current location of Glcd memory and moves to the next 
location. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 

Glcd side, x-axis position and page should be set first. See the functions 
SPI_Glcd_Set_Side, SPI_Glcd_Set_X, and SPI_Glcd_Set_Page. 


Example 


char data; 

data = SPI Glcd Read Data(); 
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SPI Glcd Write Data 



Prototype 


void SPI Glcd Write Data (char Ddata); 


Returns 


Nothing. 




Writes one byte to the current location in Glcd memory and moves to the next 




location. 


Description 


Parameters: 




- Ddata: data to be written 




Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Requires 


Glcd side, x-axis position and page should be set first. See the functions 




SPI_Glcd_Set_Side, SPI_Glcd_Set_X, and SPI_Glcd_Set_Page. 




char data; 


Example 


SPI Glcd Write Data (data); 



SPI Glcd Fi 



Prototype 


void SPI Glcd Fill (char pattern); 


Returns 


Nothing. 


Description 


Fills Glcd memory with byte pattern. 

Parameters: 

- pattern: byte to fill Glcd memory with 

To clear the Glcd screen, use spi Glcd Fiii(O). 

To fill the screen completely, use spi Glcd Fill (Oxff) . 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Clear screen 
SPI_Glcd_Fill (0) ; 
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SPI Glcd Dot 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_Glcd_Dot (char x_pos, char y_pos, char color) 



Nothing. 



Draws a dot on Glcd at coordinates (x_pos, y pos). 
Parameters: 

- x pos: x position. Valid values: 0..127 

- y pos: y position. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the dot state: clears dot, 1 puts a dot, and 2 
inverts dot state. 

Note: For x and y axis layout explanation see schematic at the bottom of this page. 



Glcd needs to be initialized for SPI communication, see SPI Glcd Init routines. 



// Invert the dot in the upper left corner 
SPI Glcd Dot (0, 0, 2) ; 



SPI Glcd Line 



Prototype 


void SPI Glcd Line (int x start, int y start, int x end, int 
y end, char color); 


Returns 


Nothing. 


Description 


Draws a line on Glcd. 
Parameters: 

- x start: x coordinate of the line start. Valid values: 0.. 127 

- y start: y coordinate of the line start. Valid values: 0.. 63 

- x end: x coordinate of the line end. Valid values: 0.. 127 

- y end: y coordinate of the line end. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

Parameter color determines the line color: white, 1 black, and 2 inverts each 
dot. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Draw a line between dots (0,0) and (20,30) 
SPI Glcd Line(0, 0, 20, 30, 1); 
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SPI Glcd V Line 



Prototype 


void SPI Glcd V Line (char y start, char y end, char x pos, char 

color) ; 


Returns 


Nothing. 


Description 


Draws a vertical line on Glcd. 
Parameters: 

-y start: y coordinate of the line start. Valid values: 0..63 

- y end: y coordinate of the line end. Valid values: 0..63 

- x pos: x coordinate of vertical line. Valid values: 0..127 

- color: color parameter. Valid values: 0..2 

Parameter color determines the line color: white, 1 black, and 2 inverts each dot. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Draw a vertical line between dots (10,5) and (10,25) 
SPI Glcd V Line (5, 25, 10, 1); 



SPI Glcd H Line 



Prototype 


void SPI Glcd H Line (char x start, char x end, char y pos, char 
color) ; 


Returns 


Nothing. 


Description 


Draws a horizontal line on Glcd. 
Parameters: 

- x start: x coordinate of the line start. Valid values: 0..127 

- x end: x coordinate of the line end. Valid values: 0..127 

- y pos: y coordinate of horizontal line. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the line color: white, 1 black, and 2 inverts 
each dot. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Draw a horizontal line between dots (10,20) and (50,20) 
SPI_Glcd_H_Line (10, 50, 20, 1); 
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SPI_Glcd_Rectangle 



Prototype 


void SPI Glcd Rectangle (char x upper left, char y upper left, 
char x bottom right, char y bottom right, char color) ; 


Returns 


Nothing. 


Description 


Draws a rectangle on Glcd. 

Parameters: 

- x upper left: x coordinate of the upper left rectangle corner. Valid values: 
0..127 

- y upper left: y coordinate of the upper left rectangle corner. Valid values: 0..63 

- x bottom right: x coordinate of the lower right rectangle corner. Valid val- 
ues: 0..127 

- y bottom right: y coordinate of the lower right rectangle corner. Valid val- 
ues: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the rectangle border: white, 1 
black, and 2 inverts each dot. 


Requires 


GLCD needs to be initialized for SPI communication, see SpiGlcdlnit routines. 


Example 


// Draw a box between dots (5,15) and (20,40) 
Spi_Glcd_Box (5, 15, 20, 40, 1); 



SPI Glcd Box 



Prototype 


void SPI Glcd Box (char x upper left, char y upper left, char 
x bottom right, char y bottom right, char color); 


Returns 


Nothing. 


Description 


Draws a box on Glcd. 

Parameters: 

- x upper left: x coordinate of the upper left box corner. Valid values: 0..127 

- y upper left: y coordinate of the upper left box corner. Valid values: 0..63 

- x bottom right: x coordinate of the lower right box corner. Valid values: 0..127 

- y bottom right: y coordinate of the lower right box corner. Valid values: 0..63 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the box fill: white, 1 black, and 2 
inverts each dot. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Draw a box between dots (5,15) and (20,40) 
SPI_Glcd_Box (5, 15, 20, 40, 1); 
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SPI Glcd Circle 



Prototype 


void SPI Glcd Circle (int x center, int y center, int radius, char 

color) ; 


Returns 


Nothing. 


Description 


Draws a circle on Glcd. 

Parameters: 

- x center: x coordinate of the circle center. Valid values: 0..127 

- y center: y coordinate of the circle center. Valid values: 0..63 

- radius: radius size 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the circle line: white, 1 black, 
and 2 inverts each dot. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routine. 


Example 


// Draw a circle with center in (50,50) and radius=10 
SPI_Glcd_Circle (50, 50, 10, 1); 



SPI Glcd Set Font 



Prototype 


void SPI Glcd Set Font (const code char *activeFont, char 
aFontWidth, char aFontHeight, unsigned int aFontOffs); 


Returns 


Nothing. 


Description 


Sets font that will be used with SPI_Glcd_Write_Char and SPI_Glcd_Write_Text 
routines. 

Parameters: 

- activeFont: font to be set. Needs to be formatted as an array of char 

- aFontwidth: width of the font characters in dots. 

- aFontHeight: height of the font characters in dots. 

- aFontof f s: number that represents difference between the mikroC PRO char- 
acter set and regular ASCII set (eg. if 'A' is 65 in ASCII character, and 'A' is 45 
in the mikroC PRO character set, aFontOffs is 20). Demo fonts supplied with 
the library have an offset of 32, which means that they start with space. 

The user can use fonts given in the file " Lib_Glcd_fonts" file located in the 

Uses folder or create his own fonts.. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Use the custom 5x7 font "myfont" which starts with space (32) : 
SPI Glcd Set Font (myfont, 5, 7, 32); 
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Spi_Glcd_Write_Char 



Prototype 


void SPI Glcd Write Char (char chrl, char x pos, char page num, 
char color) ; 


Returns 


Nothing. 


Description 


Prints character on GLCD. 
Parameters: 

- chrl : character to be written 

- x pos : character starting position on x-axis. Valid values: 0..(127-FontWidth) 

- page num: the number of the page on which character will be written. Valid 
values: 0..7 

- color: color parameter. Valid values: 0..2 

The parameter color determines the color of the character: white, 1 black, 
and 2 inverts each dot. 

Note: For x axis and page layout explanation see schematic at the bottom of 
this page. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 

Use the SPI_Glcd_Set_Font to specify the font for display; if no font is specified, then 
the default 5x8 font supplied with the library will be used. 


Example 


// Write character 'C' on the position 10 inside the page 2: 
SPI Glcd Write Char('C, 10, 2, 1); 
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Prototype 


void SPI Glcd Write Text (char text[ ] , char x pos, char page num, 
char color) ; 


Returns 


Nothing. 


Description 


Prints text on GLCD. 
Parameters: 

- text: text to be written 

- x pos : text starting position on x-axis. 

-page num: the number of the page on which text will be written. Valid values: 0..7 
-color: color parameter. Valid values: 0..2 

The parameter color determines the color of the text: white, 1 black, and 2 
inverts each dot. 

Note: For x axis and page layout explanation see schematic at the bottom of 
this page. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 

Use the SPI_Glcd_Set_Font to specify the font for display; if no font is specified, then 
the default 5x8 font supplied with the library will be used. 


Example 


// Write text "Hello world!" on the position 10 inside the page 2: 
SPI Glcd Write Text ("Hello world!", 10, 2, 1); 
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Spi_Glcd_lmage 



Prototype 


void SPI Glcd Image (const code char * image); 


Returns 


Nothing. 


Description 


Displays bitmap on GLCD. 

Parameters: 

- image : image to be displayed. Bitmap array can be located in both code and 
RAM memory (due to the mikroC PRO for PIC pointer to const and pointer to 
RAM equivalency). 

Use the mikroC PRO's integrated Glcd Bitmap Editor (menu option Tools > 
Glcd Bitmap Editor) to convert image to a constant array suitable for display- 
ing on Glcd. 


Requires 


Glcd needs to be initialized for SPI communication, see SPIGIcdlnit routines. 


Example 


// Draw image my image on Glcd 
SPI Glcd Image (my image); 



Library Example 

The example demonstrates how to communicate to KS0108 Glcd via the SPI module, using seri- 
al to parallel convenor MCP23S17. 

const code char truck_bmp[ 1024] ; 

// Port Expander module connections 

sbit SPExpanderRST at RC0_bit; 

sbit SPExpanderCS at RClJoit; 

sbit SPExpanderRST_Direction at TRISCOJoit; 

sbit SPExpanderCS_Direction at TRISClJoit; 

// End Port Expander module connections 



void Delay2s (){ 

Delay_ms (2000) ; 
} 

void main ( ) { 

char *someText; 
char counter; 



// 2 seconds delay function 



// If Port Expander Library uses SPI1 module 

SPI1 Init(); // Initialize SPI module used with PortExpander 



// // If Port Expander Library uses SPI2 module 
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// SPI2 lnit(); // Initialize SPI module used with PortExpander 

SPI_Glcd_Init (0) ; // Initialize Glcd via SPI 

SPI_Glcd_Fill (0x00) ; // Clear Glcd 

while (1) { 

SPI Glcd__Image (truck_bmp) ; // Draw image 

Delay2s(); Delay2s(); 

SPI_Glcd_Fill (0x00) ; // Clear Glcd 

Delay2s; 

SPI_Glcd_Box (62, 40,124,56, 1) ; // Draw box 

SPI_Glcd_Rectangle (5,5,84,35,1) ; // Draw rectangle 

SPI_Glcd_Line (0, 63, 127, 0,1); // Draw line 
Delay2s () ; 

for(counter = 5; counter < 60; counter+=5 ) { // Draw horizon- 
tal and vertical line 

Delay_ms (250) ; 

SPI_Glcd_V_Line (2, 54, counter, 1); 

SPI_Glcd_H_Line (2, 120, counter, 1); 

} 
Delay2s () ; 

SPI_Glcd_Fill (0x00) ; // Clear Glcd 

SPI_Glcd_Set_Font (Character8x7, 8, 8, 32); // Choose font, see 
Lib GLCDFonts.c in Uses folder 

SPI_Glcd_Write_Text ("mikroE", 5, 7, 2); // Write string 

for (counter = 1; counter <= 10; counter++) // Draw circles 

SPI_Glcd_Circle (63,32, 3*counter, 1); 
Delay2s () ; 

SPI_Glcd_Box (12,20, 70,63, 2); // Draw box 

Delay2s () ; 

SPI_Glcd_Fill (OxFF) ; // Fill Glcd 

SPI_Glcd_Set_Font (Character8x7, 8, 7, 32); // Change font 
someText = "8x7 Font"; 

SPI_Glcd_Write_Text (someText, 5, 1, 2); // Write string 
Delay2s () ; 

SPI_Glcd_Set_Font (System3x5, 3, 5, 32); // Change font 
someText = "3X5 CAPITALS ONLY"; 

SPI_Glcd_Write_Text (someText, 5, 3, 2); // Write string 
Delay2s () ; 
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SPI_Glcd_Set_Font (font5x7, 5, 7, 32); 
soraeText = "5x7 Font"; 

SPI_Glcd_Write_Text (someText, 5, 5, 2) 
Delay2s () ; 



// Change font 
// Write string 



SPI_Glcd_Set_Font (FontSystem5x7_v2, 5, 7, 32); // Change font 
someText = "5x7 Font (v2)"; 

SPI_Glcd_Write_Text (someText, 5, 7, 2); // Write string 
Delay2s () ; 

} 



HW Connection 




SPI Glcd HW connection 
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SPI LCD LIBRARY 

The mikroC PRO for PIC provides a library for communication with Led (with 
HD44780 compliant controllers) in 4-bit mode via SPI interface. 

For creating a custom set of Led characters use Led Custom Character Tool. 

Note: The library uses the SPI module for communication. The user must initialize 
the SPI module before using the SPI Led Library. 

For MCUs with two SPI modules it is possible to initialize both of them and then 
switch by using the spisetActive o routine. 

Note: This Library is designed to work with the mikroElektronika's Serial Led 
Adapter Board pinout. See schematic at the bottom of this page for details. 

External dependencies of SPI LCD Library 

The implementation of SPI Led Library routines is based on Port Expander Library 
routines. 

External dependencies are the same as Port Expander Library external dependen- 
cies. 



Library Routines 

- SPI_Lcd_Config 

- SPI_Lcd_Out 

- SPI_Lcd_Out_Cp 

- SPI_Lcd_Chr 

- SPI_Lcd_Chr_Cp 

- SPI Led Cmd 
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Spi_Lcd_Config 



Prototype 


void SPI Led Config(char DeviceAddress); 


Returns 


Nothing. 




Initializes the LCD module via SPI interface. 


Description 


Parameters: 




- DeviceAddress : spi expander hardware address, see schematic at the 




bottom of this page 




Global variables: 




- sPExpandercs : Chip Select line 




- SPExpanderRST : Reset line 




-SPExpandercs Direction: Direction of the Chip Select pin 


Requires 


-SPExpanderRST Direction: Direction of the Reset pin 




must be defined before using this function. 




The SPI module needs to be initialized. See SPI1 Init and SPI1 Init Advanced 




routines. 




// Port Expander module connections 




sbit SPExpanderRST at RCO bit; 




sbit SPExpanderCS at RC1 bit; 




sbit SPExpanderRST Direction at TRISCO bit; 




sbit SPExpanderCS Direction at TRISC1 bit; 


Example 


// End Port Expander module connections 




void main ( ) { 




// If Port Expander Library uses SPI module 




SPI1 Init(); // Initialize SPI module used with PortExpander 




SPI Led Config(O); // initialize Led over SPI interface 
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Spi_Lcd_Out 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI Led Out (char row, char column, char *text); 



Nothing. 



Prints text on the LCD starting from specified position. Both string variables and 
literals can be passed as a text. 

Parameters: 

- row: starting position row number 

- column: starting position column number 

- text : text to be written 



Led needs to be initialized for SPI communication, see SPI_Lcd_Config routines. 



// Write text "Hello!" on Led starting from row 1, column 3: 
SPI Led Out (1, 3, "Hello!"); 



Spi_Lcd_Out_Cp 



Prototype 


void SPI Led Out CP(char *text); 


Returns 


Nothing. 


Description 


Prints text on the LCD at current cursor position. Both string variables and liter- 
als can be passed as a text. 

Parameters: 

- text : text to be written 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd_Config routines. 


Example 


// Write text "Here!" at current cursor position: 
SPI Led Out CP ("Here ! ") ; 



Spi_Lcd_Chr 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI Led Chr (char Row, char Column, char Out Char) 



Nothing. 



Prints character on LCD at specified position. Both variables and literals can be 
passed as character. 

Parameters: 

- row: writing position row number 

- column: writing position column number 
-Out char: character to be written 



Led needs to be initialized for SPI communication, see SPI_Lcd_Config routines. 



// Write character "i" at row 2, column 
SPI Led Chr (2, 3, ' i ' ) ; 
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Spi_Lcd_Chr_Cp 



Prototype 


void SPI Led Chr CP(char Out Char) ; 


Returns 


Nothing. 


Description 


Prints character on LCD at current cursor position. Both variables and literals 
can be passed as character. 

Parameters: 

- Out char: character to be written 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd_Config routines. 


Example 


// Write character "e" at current cursor position: 
SPI Led Chr Cp ( 'e' ) ; 



Spi_Lcd_Cmd 



Prototype 


void SPI Led Cmd (char out char); 


Returns 


Nothing. 


Description 


Sends command to LCD. 

Parameters: 

- out char: command to be sent 

Note: Predefined constants can be passed to the function, see Available Led 
Commands. 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd_Config routines. 


Example 


// Clear Led display: 
SPI Led Cmd( LCD CLEAR); 
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Available LCD Commands 



Led Command 


Purpose 


LCD FIRST ROW 


Move cursor to the 1st row 


LCD SECOND ROW 


Move cursor to the 2nd row 


LCD THIRD ROW 


Move cursor to the 3rd row 


LCD FOURTH ROW 


Move cursor to the 4th row 


LCD CLEAR 


Clear display 


LCD RETURN HOME 


Return cursor to home position, returns a shifted display 
to its original position. Display data RAM is unaffected. 


LCD CURSOR OFF 


Turn off cursor 


LCD UNDERLINE ON 


Underline cursor on 


LCD BLINK CURSOR ON 


Blink cursor on 


LCD MOVE CURSOR LEFT 


Move cursor left without changing display data RAM 


LCD MOVE CURSOR RIGHT 


Move cursor right without changing display data RAM 


LCD TURN ON 


Turn LCD display on 


LCD TURN OFF 


Turn LCD display off 


LCD SHIFT LEFT 


Shift display left without changing display data RAM 


LCD SHIFT RIGHT 


Shift display right without changing display data RAM 
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Library Example 

This example demonstrates how to communicate Led via the SPI module, using 
serial to parallel convertor MCP23S17. 

char *text = "mikroElektronika" ; 

// Port Expander module connections 

sbit SPExpanderRST at RCOJoit; 

sbit SPExpanderCS at RClJoit; 

sbit SPExpanderRST_Direction at TRISCOJoit; 

sbit SPExpanderCS_Direction at TRISClJoit; 

// End Port Expander module connections 

void main ( ) { 

// If Port Expander Library uses SPI1 module 

SPI1 Init(); // Initialize SPI module used with PortExpander 

// If Port Expander Library uses SPI2 module 

// SPI2 lnit(); // Initialize SPI module used with PortExpander 

SPI Led Config(O); // Initialize Led over SPI interface 
SPI_Lcd_Cmd (_LCD_CLEAR) ; // Clear display 
SPI_Lcd_Cmd (_LCD_CURSOR_OFF) ; // Turn cursor off 

SPI_Lcd_Out (1, 6, "mikroE"); // Print text to Led, 1st row, 6th col- 
umn 

SPI_Lcd_Chr_CP ('!'); // Append ' ! ' 

SPI Led Out (2,1, text); // Print text to Led, 2nd row, 1st column 

// SPI Led Out (3, 1, "mikroE" ) ; // For Led with more than two rows 
// SPI Led Out ( 4, 15, "mikroE" ) ; // For Led with more than two rows 
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HW Connection 



MCP23S17 







SPI LCD HW connection 
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SPI LCD8 (8-BIT INTERFACE) LIBRARY 

The mikroC PRO for PIC provides a library for communication with Led (with 
HD44780 compliant controllers) in 8-bit mode via SPI interface. 

For creating a custom set of Led characters use Led Custom Character Tool. 

Note: Library uses the SPI module for communication. The user must initialize the 
SPI module before using the SPI Led Library. 

For MCUs with two SPI modules it is possible to initialize both of them and then 
switch by using the spisetActive ( ) routine. 

Note: This Library is designed to work with mikroElektronika's Serial Lcd/Glcd 
Adapter Board pinout, see schematic at the bottom of this page for details. 

External dependencies of SPI LCD Library 

The implementation of SPI Led Library routines is based on Port Expander Library 
routines. 

External dependencies are the same as Port Expander Library external dependen- 
cies. 

Library Routines 

- SPI_Lcd8_Config 

- SPI_Lcd8_Out 

- SPI_Lcd8_Out_Cp 

- SPI_Lcd8_Chr 

- SPI_Lcd8_Chr_Cp 

- SPI Lcd8 Cmd 
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Spi_Lcd8_Config 



Prototype 


void SPI Lcd8 Conf ig (char DeviceAddress); 


Returns 


Nothing. 


Description 


Initializes the LCD module via SPI interface. 

Parameters: 

- DeviceAddress : spi expander hardware address, see schematic at the 
bottom of this page 


Requires 


Global variables: 

- sPExpandercs: Chip Select line 

- SPExpanderRST: Reset line 

- SPExpandercs Direction: Direction of the Chip Select pin 

- SPExpanderRST Direction: Direction of the Reset pin 
must be defined before using this function. 

The SPI module needs to be initialized. See SPMJnit and SPI1_lnit_Advanced 
routines. 


Example 


// Port Expander module connections 

sbit SPExpanderRST at RCO bit; 

sbit SPExpanderCS at RC1 bit; 

sbit SPExpanderRST Direction at TRISCO bit; 

sbit SPExpanderCS Direction at TRISC1 bit; 

// End Port Expander module connections 

// If Port Expander Library uses SPI module 

SPI1 Init(); // Initialize SPI module used with PortExpander 

SPI Lcd8 Config(O); // intialize Led in 8bit mode via SPI 



Spi_Lcd8_Out 



Prototype 


void SPI Lcd8 Out (unsigned short row, unsigned short column, char 
*text) ; 


Returns 


Nothing. 


Description 


Prints text on LCD starting from specified position. Both string variables and lit- 
erals can be passed as a text. 

Parameters: 

- row: starting position row number 

- column: starting position column number 

- text: text to be written 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd8_Config routines. 


Example 


// Write text "Hello!" on Led starting from row 1, column 3: 
SPI_Lcd8_0ut (1, 3, "Hello!"); 
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Spi_Lcd8_Out_Cp 



Prototype 


void SPI Lcd8 Chr CP (char out char); 


Returns 


Nothing. 


Description 


Prints character on Led at current cursor position. Both variables and literals 
can be passed as character. 

Parameters: 

- text: text to be written 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd8_Config routines. 


Example 


// Write text "Here!" at current cursor position: 
SPI Lcd8 Out CpC'Here!"); 



Spi_Lcd8_Chr 



Prototype 


void SPI Lcd8 Chr (unsigned short row, unsigned short column, char 
out char) ; 


Returns 


Nothing. 


Description 


Prints character on LCD at specified position. Both variables and literals can be 
passed as character. 

Parameters: 

- row: writing position row number 

- column: writing position column number 

- out char: character to be written 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd8_Config routines. 


Example 


// Write character "i" at row 2, column 3: 
SPI Lcd8 Chr (2, 3, ' i ' ) ; 
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Spi_Lcd8_Chr_Cp 



Prototype 


void SPI Lcd8 Chr CP (char out char); 


Returns 


Nothing. 


Description 


Prints character on LCD at current cursor position. Both variables and literals 
can be passed as character. 

Parameters: 

- out char : character to be written 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd8_Config routines. 


Example 


Print "e" at current cursor position: 

// Write character "e" at current cursor position: 
SPI Lcd8 Chr Cp ( ' e ' ) ; 



Spi_Lcd8_Cmd 



Prototype 


void SPI Lcd8 Cmd(char out char); 


Returns 


Nothing. 


Description 


Sends command to LCD. 

Parameters: 

- out char: command to be sent 

Note: Predefined constants can be passed to the function, see Available LCD 
Commands. 


Requires 


Led needs to be initialized for SPI communication, see SPI_Lcd8_Config routines. 


Example 


// Clear Led display: 
SPI Lcd8 Cmd ( LCD CLEAR); 
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Available LCD Commands 



Led Command 


Purpose 


LCD FIRST ROW 


Move cursor to the 1st row 


LCD SECOND ROW 


Move cursor to the 2nd row 


LCD THIRD ROW 


Move cursor to the 3rd row 


LCD FOURTH ROW 


Move cursor to the 4th row 


LCD CLEAR 


Clear display 


LCD RETURN HOME 


Return cursor to home position, returns a shifted display 
to its original position. Display data RAM is unaffected. 


LCD CURSOR OFF 


Turn off cursor 


LCD UNDERLINE ON 


Underline cursor on 


LCD BLINK CURSOR ON 


Blink cursor on 


LCD MOVE CURSOR LEFT 


Move cursor left without changing display data RAM 


LCD MOVE CURSOR RIGHT 


Move cursor right without changing display data RAM 


LCD TURN ON 


Turn LCD display on 


LCD TURN OFF 


Turn LCD display off 


LCD SHIFT LEFT 


Shift display left without changing display data RAM 


LCD SHIFT RIGHT 


Shift display right without changing display data RAM 
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Library Example 

This example demonstrates how to communicate Led in 8-bit mode via the SPI mod- 
ule, using serial to parallel convertor MCP23S17. 

char *text = "mikroE"; 

// Port Expander module connections 

sbit SPExpanderRST at RCOJoit; 

sbit SPExpanderCS at RClJoit; 

sbit SPExpanderRST_Direction at TRISCOJoit; 

sbit SPExpanderCS_Direction at TRISClJoit; 

// End Port Expander module connections 

void main ( ) { 

// If Port Expander Library uses SPI1 module 

SPI1 Init(); // Initialize SPI module used with PortExpander 

// If Port Expander Library uses SPI2 module 

// SPI2 Init(); // Initialize SPI module used with PortExpander 

SPI_Lcd8_Conf ig (0) ; // Intialize Led in 8bit mode via SPI 
SPI_Lcd8_Cmd(_LCD_CLEAR) ; // Clear display 

SPI_Lcd8_Cmd(_LCD_CURSOR_OFF) ; // Turn cursor off 
SPI_Lcd8_Out (1, 6, text); // Print text to Led, 1st row, 6th column... 
SPI_Lcd8_Chr_CP ('!'); // Append ' ! ' 

SPI_Lcd8_Out (2, 1, "mikroElektronika") ; // Print text to Led, 2nd 
row, 1st column. . . 

SPI Lcd8 Out (3,1, text); // For Led modules with more than two rows 
SPI Lcd8 Out (4, 15, text);// For Led modules with more than two rows 
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HW Connection 
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SPI T6963C GRAPHIC LCD LIBRARY 

The mikroC PRO for PIC provides a library for working with Glcds based on 
TOSHIBA T6963C controller via SPI interface. The Toshiba T6963C is a very popu- 
lar Led controller for the use in small graphics modules. It is capable of controlling 
displays with a resolution up to 240x128. Because of its low power and small out- 
line it is most suitable for mobile applications such as PDAs, MP3 players or mobile 
measurement equipment. Although this controller is small, it has a capability of dis- 
playing and merging text and graphics and it manages all interfacing signals to the 
displays Row and Column drivers. 

For creating a custom set of Glcd images use Glcd Bitmap Editor Tool. 

Note: The library uses the SPI module for communication. The user must initialize 
SPI module before using the SPI T6963C Glcd Library. 

For MCUs with two SPI modules it is possible to initialize both of them and then 
switch by using the spisetActive ( ) routine. 

Note: This Library is designed to work with mikroElektronika's Serial Glcd 240x128 
and 240x64 Adapter Boards pinout, see schematic at the bottom of this page for 
details. 

Note: Some mikroElektronika's adapter boards have pinout different from T6369C 
datasheets. Appropriate relations between these labels are given in the table below: 



Adapter Board 


T6369C datasheet 


RS 


C/D 


R/W 


/RD 


E 


/WR 



External dependencies of Spi T6963C Graphic LCD Library 

The implementation of SPI T6963C Graphic Led Library routines is based on Port 
Expander Library routines. 

External dependencies are the same as Port Expander Library external dependen- 
cies. 
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Library Routines 

- SPI_T6963C_Config 

- SPI_T6963C_writeData 

- SPI_T6963C_writeCommand 

- SPI_T6963C_setPtr 

- SPI_T6963C_waitReady 

- SPI_T6963C_fill 

- SPI_T6963C_dot 

- SPI_T6963C_write_char 

- SPI_T6963C_write_text 

- SPI_T6963CJine 

- SPI_T6963C_rectangle 

- SPI_T6963C_box 

- SPI_T6963C_circle 

- SPI_T6963C_image 

- SPI_T6963C_sprite 

- SPI_T6963C_set_cursor 

- SPI_T6963C_clearBit 

- SPI_T6963C_setBit 

- SPI_T6963C_negBit 

Note: The following low level library routines are implemented as macros. These 
macros can be found in the spi T6963c.h header file which is located in the SPI 
T6963C example projects folders. 

- SPI_T6963C_displayGrPanel 

- SPI_T6963C_displayTxtPanel 

- SPI_T6963C_setGrPanel 

- SPI_T6963C_setTxtPanel 

- SPI_T6963C_panelFill 

- SPI_T6963C_grFill 

- SPI_T6963C_txtFill 

- SPI_T6963C_cursor_height 

- SPI_T6963C_graphics 

- SPI_T6963C_text 

- SPI_T6963C_cursor 

- SPI T6963C cursor blink 
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Spi_T6963C_Config 



Prototype 



Returns 



Description 



void SPI_T6963C_Config (unsigned int width, unsigned char height, 
unsigned char fntw, char DeviceAddress , unsigned char wr, 
unsigned char rd, unsigned char cd, unsigned char rst) ; 



Nothing. 



Initalizes the Graphic Led controller. 
Parameters: 

- width : width of the GLCD panel 

- height : height of the GLCD panel 

- fntw: font width 

- DeviceAddress : SPI expander hardware address, see schematic at the 
bottom of this page 

- wr: write signal pin on GLCD control port 

- rd: read signal pin on GLCD control port 

- cd: command/data signal pin on GLCD control port 

- rst : reset signal pin on GLCD control port 

Display RAM organization: 

The library cuts RAM into panels : a complete panel is one graphics panel fol- 
lowed by a text panel (see schematic below). 

schematic: 

+ + /\ 

+ GRAPHICS PANEL #0 + I 

+ + I 

+ + I 

+ + I 

+ + | PANEL 

+ TEXT PANEL #0 + | 

+ + \/ 

+ + /\ 

+ GRAPHICS PANEL #1 + | 

+ + I 

+ + I 

+ + I 

+ + | PANEL 1 

+ TEXT PANEL #1 + | 

+ + I 

+ + \/ 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 509 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



Requires 



Example 



Global variables: 

SPExpandercs: Chip Select line 

SPExpanderRST: Reset line 

SPExpandercsDirection: Direction of the Chip Select pin 

SPExpanderRSTDirection: Direction of the Reset pin 
must be defined before using this function. 

The SPI module needs to be initialized. See the SPHInit and 
SPI1 Init Advanced routines. 



// Port Expander module connections 

sbit SPExpanderRST at RCOJoit; 

sbit SPExpanderCS at RCl_bit; 

sbit SPExpanderRST_Direction at TRISCOJoit; 

sbit SPExpanderCS_Direction at TRISClJoit; 

// End Port Expander module connections 



// Initialize SPI module 
SPIl_Init () ; 
SPI_T6963C_Config(240, 64, 



i , , , 1 , 3 , 4 ) ; 



Spi_T6963C. 


WriteData 




Prototype 


void SPI T6963C writeData (unsigned char Ddata); 


Returns 


Nothing. 


Description 


Writes data to T6963C controller via SPI interface. 

Parameters: 

- Ddata : data to be written 


Requires 


Toshiba Glcd module needs to be initialized. See SPIT6963C 


Config routine. 


Example 


SPI T6963C writeData (AddrL) ; 



Spi_T6963C_WriteCommand 



Prototype 


void SPI T6963C writeCommand (unsigned char Ddata); 


Returns 


Nothing. 


Description 


Writes command to T6963C controller via SPI interface. 

Parameters: 

- Ddata : command to be written 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI T6963C writeCommand (SPI T6963C CURSOR POINTER SET); 
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Spi_T6963C_SetPtr 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_T6963C_setPtr (unsigned int p, unsigned char c) ; 



Nothing. 



Sets the memory pointer p for command c. 
Parameters: 

- p : address where command should be written 

- c : command to be written 



SToshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



SPI_T6963C_setPtr (T6963C_grHomeAddr + start, 
T6963C ADDRESS POINTER SET); 



Spi_T6963C_WaitReady 



Prototype 


void SPI T6963C waitReady (void) ; 


Returns 


Nothing. 


Description 


Pools the status byte, and loops until Toshiba Glcd module is ready. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI T6963C waitReady () ; 



Spi_T6963C_Fil 



Prototype 


void SPI T6963C fill (unsigned char v, unsigned int start, 
unsigned int len) ; 


Returns 


Nothing. 


Description 


Fills controller memory block with given byte. 
Parameters: 

- v: byte to be written 

- start : starting address of the memory block 

- len : length of the memory block in bytes 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI_T6963C_fill (0x33,0x00FF, OxOOOF) ; 
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Spi_T6963C. 


Dot 


Prototype 


void SPI T6963C dot (int x, int y, unsigned char color); 


Returns 


Nothing. 


Description 


Draws a dot in the current graphic panel of GLCD at coordinates (x, y). 
Parameters: 

- x : dot position on x-axis 

- y: dot position on y-axis 

-color: color parameter. Valid values: Spi T6963C BLACK and 
Spi_T6963C_WHITE 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI_T6963C_dot (xO, yO, pcolor) ; 
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Spi_T6963C_Write_Char 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_T6963C_write_char (unsigned char c, unsigned char x, 
unsigned char y, unsigned char mode) ; 



Nothing. 



Writes a char in the current text panel of GLCD at coordinates (x, y). 
Parameters: 

- c : char to be written 

- x: char position on x-axis 

- y: char position on y-axis 

- mode: mode parameter. Valid values: 

SPI_T6963C_ROM_MODE_OR, SPI_T6963C_ROM_MODE_XOR, 
SPI_T6963C_ROM_MODE_AND and 
SPI_T6963C_ROM_MODE_TEXT 

Mode parameter explanation: 

- OR Mode: In the OR-Mode, text and graphics can be displayed and the data 
is logically "OR-ed". This is the most common way of combining text and 
graphics for example labels on buttons. 

- XOR-Mode: In this mode, the text and graphics data are combined via the 
logical "exclusive OR". This can be useful to display text in negative mode, 
i.e. white text on black background. 

- AND-Mode: The text and graphic data shown on display are combined via 
the logical "AND function". 

- TEXT-Mode: This option is only available when displaying just a text. The 
Text Attribute values are stored in the graphic area of display memory. 

For more details see the T6963C datasheet. 



Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



SPI T6963C write char ( "A", 22, 23, AND) ; 
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Spi_T6963C_write_Text 



Prototype 


void SPI T6963C write text (unsigned char *str, unsigned char x, 
unsigned char y, unsigned char mode) ; 


Returns 


Nothing. 


Description 


Writes text in the current text panel of GLCD at coordinates (x, y). 
Parameters: 

- str : text to be written 

- x : text position on x-axis 

- y : text position on y-axis 

- mode : mode parameter. Valid values: 

SPI_T6963C_ROM MODEJDR, SPI_T6963C ROM MODE_XOR, 
SPI_T6963C ROM MODE AND and 
SPI_T6963C_ROM_MODE_TEXT 

Mode parameter explanation: 

- OR Mode: In the OR-Mode, text and graphics can be displayed and the data 
is logically "OR-ed". This is the most common way of combining text and 
graphics for example labels on buttons. 

- XOR-Mode: In this mode, the text and graphics data are combined via the 
logical "exclusive OR". This can be useful to display text in negative mode, 
i.e. white text on black background. 

- AND-Mode: The text and graphic data shown on the display are combined 
via the logical "AND function". 

- TEXT-Mode: This option is only available when displaying just a text. The 
Text Attribute values are stored in the graphic area of display memory. 

For more details see the T6963C datasheet. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI T6963C write text ("Glcd LIBRARY DEMO, WELCOME !", 0, 0, 
T6963C ROM MODE EXOR) ; 



514 MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 



mikroC PRO for PIC 



CHAPTER 7 
Libraries 



Spi_T6963C_line 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_T6963C_line (int xO, int yO, int xl, int yl, unsigned 

char pcolor) ; 



Nothing. 



Draws a line from (xO, yO) to (x1 , y1 ). 
Parameters: 

- xO : x coordinate of the line start 

- yO : y coordinate of the line end 

- xi : x coordinate of the line start 

- yi : y coordinate of the line end 

- pcolor: color parameter. Valid values: 

SPI T6963C BLACK and SPI T6963C WHITE 



Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



SPI T6963C line(0, 0, 239, 127, T6963C WHITE); 



Spi_T6963C_rectangle 



Prototype 



void SPI_T6963C_rectangle (int xO, int yO, int xl, int yl, 
unsigned char pcolor) ; 



Returns 



Nothing. 



Description 



Draws a rectangle on GLCD. 
Parameters: 

- xO : x coordinate of the upper left rectangle corner 

- yO : y coordinate of the upper left rectangle corner 

- xi : x coordinate of the lower right rectangle corner 

- yi : y coordinate of the lower right rectangle corner 

- pcolor: color parameter. Valid values: 

SPI T6963C BLACK and SPI T6963C WHITE 



Requires 



Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



Example 



SPI_T6963C_rectangle (20, 20, 219, 107, T6963C_WHITE) ; 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 51 5 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



Spi_T6963C_box 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_T6963C_box (int xO, int yO , int xl, int yl , unsigned char 

pcolor ) ; 



Nothing. 



Draws a box on the GLCD 



Parameters: 



xO 
yO 
xl 

yi 



x coordinate of the upper left box corner 



y coordinate of the upper left box corner 
x coordinate of the lower right box corner 
y coordinate of the lower right box corner 
pcolor: color parameter. Valid values: 
SPI T6963C BLACK and SPI T6963C WHITE 



Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



SPI T6963C box(0, 119, 239, 127, T6963C WHITE); 



Spi_T6963C_circle 



Prototype 


void SPI T6963C circle (int x, int y, long r, unsigned char pcol- 
or) ; 


Returns 


Nothing. 


Description 


Draws a circle on the GLCD. 
Parameters: 

- x : x coordinate of the circle center 

- y: y coordinate of the circle center 

- r : radius size 

- pcolor: color parameter. Valid values: 
SPI_T6963C_BLACK and SPI_T6963C_WHITE 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI T6963C circle(120, 64, 110, T6963C WHITE); 
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Spi_T6963C. 


image 


Prototype 


void SPI T6963C image (const code char *pic) ; 


Returns 


Nothing. 




Displays bitmap on GLCD. 




Parameters: 




- pic : image to be displayed. Bitmap array can be located in both code and 




RAM memory (due to the mikroC PRO for PIC pointer to const and pointer to 


Description 


RAM equivalency). 




Use the mikroC PRO's integrated Glcd Bitmap Editor (menu option Tools > 




Glcd Bitmap Editor) to convert image to a constant array suitable for display- 




ing on Glcd. 




Note: Image dimension must match the display dimension. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI T6963C image (my image); 



Spi_T6963C_Sprite 



Prototype 



void SPI_T6963C_sprite (unsigned char px, unsigned char py, const 
code char *pic, unsigned char sx, unsigned char sy) ; 



Returns 



Nothing. 



Description 



Fills graphic rectangle area (px, py) to (px+sx, py+sy) with custom size picture. 
Parameters: 

- px: x coordinate of the upper left picture corner. Valid values: multiples of the 
font width 

- py: y coordinate of the upper left picture corner 

- pic : picture to be displayed 

- sx: picture width. Valid values: multiples of the font width 

- sy: picture height 

Note: If px and sx parameters are not multiples of the font width they will be 
scaled to the nearest lower number that is a multiple of the font width. 



Requires 



Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



Example 



SPI_T6963C_sprite (76, 4, einstein, 



!, 119); // draw a sprite 
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Spi_T6963C_set_cursor 



Prototype 


void SPI T6963C set cursor (unsigned char x, unsigned char y) ; 


Returns 


Nothing. 




Sets cursor to row x and column y. 


Description 


Parameters: 




- x: cursor position row number 




- y: cursor position column number 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


SPI T6963C set cursor (cposx, cposy) ; 



Spi_T6963C_clearBit 



Prototype 


void SPI T6963C clearBit (char b) ; 


Returns 


Nothing. 


Description 


Clears control port bit(s). 

Parameters: 

- b : bit mask. The function will clear bit x on control port if bit x in bit mask is set to 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// clear bits and 1 on control port 
SPI_T6963C_clearBit (0x03) ; 



Spi_T6963C_setBit 



Prototype 


void SPI T6963C setBit (char b) ; 


Returns 


Nothing. 


Description 


Sets control port bit(s). 

Parameters: 

- b : bit mask. The function will set bit x on control port if bit x in bit mask is set to 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// set bits and 1 on control port 
SPI T6963C setBit (0x03) ; 
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Spi_T6963C_negBit 



Prototype 


void SPI T6963C negBit (char b) ; 


Returns 


Nothing. 


Description 


Negates control port bit(s). 

Parameters: 

- b : bit mask. The function will negate bit x on control port if bit x in bit mask is 
set to 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// negate bits and 1 on control port 
SPI T6963C negBit (0x03) ; 



Spi_T6963C_DisplayGrPanel 



Prototype 


void SPI T6963C displayGrPanel (char n) ; 


Returns 


Nothing. 


Description 


Display selected graphic panel. 

Parameters: 

- n : graphic panel number. Valid values: and 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// display graphic panel 1 
SPI T6963C displayGrPanel (1) ; 



Spi_T6963C_displayTxtPanel 



Prototype 


void SPI T6963C displayTxtPanel (char n) ; 


Returns 


Nothing. 


Description 


Display selected text panel. 

Parameters: 

- n: text panel number. Valid values: and 1. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// display text panel 1 

SPI T6963C displayTxtPanel (1) ; 
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Spi_T6963C_setGrPanel 



Prototype 


void SPI T6963C setGrPanel (char n) ; 


Returns 


Nothing. 


Description 


Compute start address for selected graphic panel and set appropriate internal 
pointers. All subsequent graphic operations will be preformed at this graphic 
panel. 

Parameters: 

- n: graphic panel number. Valid values: and 1. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// set graphic panel 1 as current graphic panel. 
SPI_T6963C_setGrPanel (1) ; 



Spi_T6963C_setTxtPanel 



Prototype 


void SPI T6963C setTxtPanel (char n) ; 


Returns 


Nothing. 


Description 


Compute start address for selected text panel and set appropriate internal point- 
ers. All subsequent text operations will be preformed at this text panel. 

Parameters: 

- n: text panel number. Valid values: and 1. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// set text panel 1 as current text panel. 
SPI T6963C setTxtPanel (1) ; 
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Spi_T6963C_panelFill 



Prototype 


void SPI T6963C panelFill (unsigned char v) ; 


Returns 


Nothing. 


Description 


Fill current panel in full (graphic+text) with appropriate value (0 to clear). 

Parameters: 

- v : value to fill panel with. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


clear current panel 

SPI T6963C panelFill (0) ; 



Spi_T6963C_GrFil 



Prototype 


void SPI T6963C grFi 11 (unsigned char v) ; 


Returns 


Nothing. 


Description 


Fill current graphic panel with appropriate value (0 to clear). 

Parameters: 

- v: value to fill graphic panel with. 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// clear current graphic panel 
SPI_T6963C_grFill (0) ; 



Spi_T6963C. 


.txtFill 




Prototype 


void SPI T6963C txtFill (unsigned char v) ; 


Returns 


Nothing. 


Description 


Fill current text panel with appropriate value (0 to clear). 

Parameters: 

- v: this value increased by 32 will be used to fill text panel. 


Requires 


Toshiba Glcd module needs to be initialized. See SPIT6963C 


Config routine. 


Example 


// clear current text panel 
SPI T6963C txtFill (0); 
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Spi_T6963C_cursor_height 



Prototype 



Returns 



Description 



Requires 



Example 



void SPI_T6963C_cursor_height (unsigned char n) ; 



Nothing. 



Set cursor size. 

Parameters: 

- r. : cursor height. Valid values: o . . 7. 



Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 



SPI_T6963C_cursor_height (7) ; 



Spi_T6963C_graphics 



Prototype 


void SPI T6963C graphics (char n) ; 


Returns 


Nothing. 


Description 


Enable/disable graphic displaying. 

Parameters: 

- n: graphic enable/disable parameter. Valid values: o (disable graphic 
dispaying) and : (enable graphic displaying). 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// enable graphic displaying 
SPI_T6963C_graphics (1) ; 



Spi_T6963C_text 



Prototype 


void SPI T6963C text (char n) ; 


Returns 


Nothing. 


Description 


Enable/disable text displaying. 

Parameters: 

- n: text enable/disable parameter. Valid values: o (disable text dispaying) and : 
(enable text displaying). 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// enable text displaying 
SPI_T6963C_text (1) ; 
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Spi_T6963C_cursor 



Prototype 


void SPI T6963C cursor (char n) ; 


Returns 


Nothing. 


Description 


Set cursor on/off. 

Parameters: 

- r. : on/off parameter. Valid values: (set cursor off) and 1 (set cursor on). 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// set cursor on 
SPI_T6963C_cursor (1) ; 



Spi_T6963C_cursor_blink 



Prototype 


void SPI T6963C cursor blink (char n) ; 


Returns 


Nothing. 


Description 


Enable/disable cursor blinking. 

Parameters: 

- n: cursor blinking enable/disable parameter. Valid values: o (disable cursor 
blinking) and 1 (enable cursor blinking). 


Requires 


Toshiba Glcd module needs to be initialized. See SPI_T6963C_Config routine. 


Example 


// enable cursor blinking 
SPI T6963C cursor blink(l); 



Library Example 

The following drawing demo tests advanced routines of the SPI T6963C Glcd library. Hardware 
configurations in this example are made for the T6963C 240x128 display, EasyPIC5 board and 
16F887. 
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#include " SPIT6963C.h" 

/* 

* bitmap pictures stored in ROM 

*/ 
extern const code char me[ ] ; 
extern const code char einstein[ ] ; 

// Port Expander module connections 

sbit SPExpanderRST at RCOJoit; 

sbit SPExpanderCS at RClJoit; 

sbit SPExpanderRST_Direction at TRISCOJoit; 

sbit SPExpanderCS_Direction at TRISClJoit; 

// End Port Expander module connections 



void main ( ) { 

char txtl[ ] 
char txt[ ] = 



EINSTEIN WOULD HAVE LIKED mE ' 
GLCD LIBRARY DEMO, WELCOME !' 



unsigned char 
unsigned int 
unsigned char 
unsigned int 

TRISA = OxFF; 
ANSEL = ; 
ANSELH = 0; 



panel; 

i ; 

curs ; 

cposx, cposy; 



// current panel 

// general purpose register 

// cursor visibility 

// cursor x-y position 

// Configure PORTA as input 

// Configure AN pins as digital I/O 



// If Port Expander Library uses SPI1 module 

SPI1 Init(); // Initialize SPI module used with PortExpander 

// // If Port Expander Library uses SPI2 module 

// SPI2 lnit(); // Initialize SPI module used with PortExpander 



/* 



init display for 240 pixel width and 128 pixel height 

8 bits character width 

data bus on MCP23S17 portB 

control bus on MCP23S17 portA 

bit 2 is !WR 

bit 1 is !RD 

bit is !CD 

bit 4 is RST 

chip enable, reverse on, 8x8 font internaly set in library 



*/ 



SPI_T6963C_Config (240, 12? 
Delay_ms (1000) ; 



0, 2, 1, 0, 4) 
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/* 



Enable both graphics and text display at the same time 



*/ 

SPI_T6963C_graphics (1) ; 
SPI_T6963C_text (1) ; 

panel = 0; 

i = 0; 

curs = ; 

cposx = cposy = ; 



/* 



Text messages 



*/ 
SPI_T6963C_write_text (txt, 0, 0, SPI_T6963C_ROM_MODE_XOR) ; 
SPI T6963C write text(txtl, 0, 15, SPI T6963C ROM MODE XOR) 



/* 

* Cursor 

*/ 
SPI_T6963C_cursor_height ( 8 ) ; 
SPI_T6963C_set_cursor (0, ) ; 
SPI T6963C cursor (0) ; 



// 8 pixel height 
// move cursor to top left 
// cursor off 



/* 



Draw rectangles 



/ 



SPI_T6963C_rectangle (0, 0, 239, 127, SPI_T6963C_WHTTE) ; 
SPI_T6963C_rectangle (20, 20, 219, 107, SPI_T6963C_WHITE) 
SPI_T6963C_rectangle (40, 40, 199, 87, SPI_T6963C_WHITE) ; 
SPI_T6963C_rectangle (60, 60, 179, 67, SPI_T6963C_WHITE) ; 



/■> 



Draw a cross 



*/ 

SPI_T6963C_line (0, 0, 239, 127, SPI_T6963C_WHITE) ; 
SPI_T6963C_line (0, 127, 239, 0, SPI_T6963C_WHITE) ; 

/* 

* Draw solid boxes 

*/ 
SPI_T6963C_box(0, 0, 239, 8, SPI_T6963C_WHITE) ; 
SPI T6963C box(0, 119, 239, 127, SPI T6963C WHITE); 



* Draw circles 

*/ 

SPI_T6963C_circle (120, 64, 10, SPI_T6963C_WHITE ) 

SPI_T6963C_circle (120, 64, 30, SPI_T6963C_WHITE) 

SPI T6963C circle (120, 64, 50, SPI T6963C WHITE) 
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SPI_T6963C_circle (120, 64, 70, SPI_T6963C_WHITE ) ; 

SPI_T6963C_circle (120, 64, 90, SPI_T6963C_WHITE) ; 

SPI_T6963C_circle (120, 64, 110, SPI_T6963C_WHITE) ; 

SPI_T6963C_circle (120, 64, 130, SPI_T6963C_WHITE) ; 

SPI_T6963C_sprite (76, 4, einstein, 88, 119); // Draw a sprite 

SPI_T6963C_setGrPanel (1) ; // Select other graphic panel 

SPI T6963C image (me ) ; // Fill the graphic screen with a picture 

while (1) { // Endless loop 

/* 

* If PORTA is pressed, toggle the display between graphic 
panel and graphic 1 
*/ 
if(RA0_bit) { 
panel++; 
panel &= 1 ; 

SPI_T6963C_displayGrPanel (panel) ; 
Delay_ms (300) ; 
} 

/* 

* If PORTA 1 is pressed, display only graphic panel 
*/ 

else if(RAlJoit) { 

SPI_T6963C_graphics (1) ; 
SPI_T6963C_text (0) ; 
Delay_ms (300) ; 
} 

/* 

* If PORTA_2 is pressed, display only text panel 
*/ 

else if(RA2_bit) { 

SPI_T6963C_graphics (0) ; 
SPI_T6963C_text (1) ; 
Delay_ms (300) ; 
} 

/* 

* If PORTA 3 is pressed, display text and graphic panels 
*/ 

else if(RA3_bit) { 

SPI_T6963C_graphics (1) ; 
SPI_T6963C_text (1) ; 
Delay_ms (300) ; 
} 

/* 
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* If PORTA_4 is pressed, change cursor 
*/ 

else if(RA4_bit) { 
curs++; 

if(curs == 3) curs = 0; 
switch (curs) { 
case : 

// no cursor 
SPI_T6963C_cursor (0) ; 
break; 
case 1 : 

// blinking cursor 
SPI_T6963C_cursor (1) ; 
SPI_T6963C_cursor_blink (1) ; 
break ; 
case 2 : 

// non blinking cursor 
SPI_T6963C_cursor (1) ; 
SPI_T6963C_cursor_blink (0) ; 
break; 
} 
Delay_ms (300) ; 
} 

/* 

* Move cursor, even if not visible 
*/ 

cposx++; 

if(cposx == SPI_T6963C_txtCols) { 

cposx = 0; 

cposy++; 
if(cposy == SPI_T6963C_grHeight / SPI_T6963C_CHARACTER_HEIGHT) 



f 



cposy = 0; 
} 
} 
SPI_T6963C_set_cursor (cposx, cposy) 

Delay_ms (100) ; 



1 
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HW Connection 




Contrast 

Adjustment 



Spi T6963C GLCD HW connection 
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T6963C GRAPHIC LCD LIBRARY 

The mikroC PRO for PIC provides a library for working with Glcds based on 
TOSHIBA T6963C controller. The Toshiba T6963C is a very popular Led controller 
for the use in small graphics modules. It is capable of controlling displays with a res- 
olution up to 240x1 28. Because of its low power and small outline it is most suitable 
for mobile applications such as PDAs, MP3 players or mobile measurement equip- 
ment. Although small, this contoller has a capability of displaying and merging text 
and graphics and it manages all the interfacing signals to the displays Row and Col- 
umn drivers. 

For creating a custom set of Glcd images use Glcd Bitmap Editor Tool. 

Note: ChipEnable(CE), FontSelect(FS) and Reverse(MD) have to be set to appro- 
priate levels by the user outside of the T6963C init function. See the Library 
Example code at the bottom of this page. 

Note: Some mikroElektronika's adapter boards have pinout different from T6369C 
datasheets. Appropriate relations between these labels are given in the table below: 



Adapter Board 


T6369C datasheet 


RS 


C/D 


R/W 


/RD 


E 


/WR 
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External dependencies of T6963C Graphic LCD Library 



The following variables must 

be defined in all projects 

using T6963C Graphic LCD 

library: 


Description: 


Example: 


extern sfr char 

T6963C dataPort; 


T6963C Data Port. 


PORTD; 


extern sfr sbit 

T6963C ctrlwr; 


Write signal. 


RC2 bit; 


extern sfr sbit 

T6963C ctrlrd; 


Read signal. 


RC1 bit; 


extern sfr sbit 

T6963C_ctrlcd; 


Command/Data 
signal. 


RCO bit; 


extern sfr sbit 

T6963C ctrlrst; 


Reset signal. 


RC4 bit; 


extern sfr sbit 

T6963C ctrlwr Direction; 


Direction of the 
Write pin. 


sbit 

T6963C ctrlwr Direction 
at TRISC2 bit; 


extern sfr sbit 

T6963C ctrlrd Direction; 


Direction of the 
Read pin. 


T6963C ctrlrd Direction 


extern sfr sbit 

T6963C ctrlcd Direction; 


Direction of the 
Data pin. 


sbit 

T6963C ctrlcd Direction 
at TRISCO bit; 


extern sfr sbit 

T6963C ctrlrst Direction; 


Direction of the 
Reset pin. 


sbit 

T6963C ctrlrst Direction 
at TRISC4 bit; 
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Library Routines 

- T6963C_init 

- T6963C_writeData 

- T6963C_writeCommand 

- T6963C_setPtr 

- T6963C_waitReady 

- T6963C_fill 

- T6963C_dot 

- T6963C_write_char 

- T6963C_write_text 

- T6963CJine 

- T6963C_rectangle 

- T6963C_box 

- T6963C_circle 

- T6963C_image 

- T6963C_sprite 

- T6963C_set_cursor 

Note: The following low level library routines are implemented as macros. These 
macros can be found in the T6963c.h header file which is located in the T6963C 
example projects folders. 

- T6963C_clearBit 

- T6963C_setBit 

- T6963C_negBit 

- T6963C_displayGrPanel 

- T6963C_displayTxtPanel 

- T6963C_setGrPanel 

- T6963C_setTxtPanel 

- T6963C_panelFill 

- T6963C_grFill 

- T6963C_txtFill 

- T6963C_cursor_height 

- T6963C_graphics 

- T6963C_text 

- T6963C_cursor 

- T6963C cursor blink 
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T6963C Init 



Prototype 


void T6963C init (unsigned int width, unsigned char height, 
unsigned char fntW) ; 


Returns 


Nothing. 


Description 


Initalizes the Graphic Led controller. 

Parameters: 

- width : width of the GLCD panel 

- height : height of the GLCD panel 

- fntw: font width 

Display RAM organization: 

The library cuts the RAM into panels: a complete panel is one graphics panel 

followed by a text panel (see schematic below). 

schematic : 


+ GRAPHICS PANEL #0 + | 
+ + 1 
+ + 1 
+ + 1 


+ TEXT PANEL #0 + | 
+ + \/ 


+ GRAPHICS PANEL #1 + | 

+ + 1 

+ + 1 

+ + 1 

+ + | PANEL 1 

+ TEXT PANEL #1 + | 

+ + 1 
+ + \/ 


Requires 


Global variables: 

- T6963C dataPort: Data Port 

- T6963C ctriwr: Write signal pin 

- T6963C ctrird: Read signal pin 

- T6963C ctricd: Command/Data signal pin 

- T6963c_ctrirst : Reset signal pin 

- T6963C ctriwr Direction: Direction of Write signal pin 

- T6963C ctrird Direction: Direction of Read signal pin 

- T6963C ctricd Direction: Direction of Command/Data signal pin 

- T6963C ctrirst Direction: Direction of Reset signal pin 

must be defined before using this function. 
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// T6963C module connections 






char T6963C dataPort at PORTD; 






sbit T6963C ctrlwr at RC2 bit; 






sbit T6963C ctrlrd at RC1 bit; 






sbit T6963C ctrlcd at RCO bit; 






sbit T6963C ctrlrst at RC4 bit; 






sbit T6963C ctrlwr Direction at 


TRISC2 bit; 




sbit T6963C ctrlrd Direction at 


TRISC1 bit; 




sbit T6963C ctrlcd Direction at 


TRISCO bit; 




sbit T6963C ctrlrst Direction at 


TRISC4 bit; 




// End of T6963C module connections 




// Signals not used by library, 


they are set in main function 




sbit T6963C ctrlce at RC3 bit; 


// CE signal 


Example 


sbit T6963C ctrlfs at RC6 bit; 


// FS signal 




sbit T6963C ctrlmd at RC5 bit; 


// MD signal 




sbit T6963C ctrlce Direction at 


TRISC3 bit;// CE signal direc- 




tion 






sbit T6963C ctrlfs Direction at 


TRISC6 bit; // FS signal 




direction 






sbit T6963C ctrlmd Direction at 


TRISC5 bit; // MD signal 




direction 






// End T6963C module connections 






// init display for 240 pixel wi 


dth, 128 pixel height and 8 bits 




character width 






T6963C_init (240, 128, 8); 





T6963C writeData 



Prototype 


void T6963C writeData (unsigned char mydata); 


Returns 


Nothing. 


Description 


Writes data to T6963C controller. 

Parameters: 

- mydata: data to be written 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C writeData (AddrL) ; 
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T6963C WriteCommand 



Prototype 



Returns 



Description 



Requires 



Example 



void T6963C_writeCommand (unsigned char mydata); 



Nothing. 



Writes command to T6963C controller. 

Parameters: 

- mydata: command to be written 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



T6963C writeCommand(T6963C CURSOR POINTER SET); 



T6963C SetPtr 



Prototype 



void T6963C_setPtr (unsigned int p, unsigned char c) 



Returns 



Nothing. 



Description 



Sets the memory pointer p for command c. 
Parameters: 

- p : address where command should be written 

- c : command to be written 



Requires 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



Example 



T6963C_setPtr (T6963C_grHomeAddr + start, 
T6963C ADDRESS POINTER SET); 



T6963C_waitReady 



Prototype 


void T6963C waitReady (void) ; 


Returns 


Nothing. 


Description 


Pools the status byte, and loops until Toshiba GLCD module is ready. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C waitReady () ; 
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T6963C fill 



Prototype 


void T6963C fill (unsigned char v, unsigned int start, unsigned 

int len) ; 


Returns 


Nothing. 


Description 


Fills controller memory block with given byte. 
Parameters: 

- v: byte to be written 

- start : starting address of the memory block 

- len : length of the memory block in bytes 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6 963C_fill (0x33, 0x0 OFF, 0x00 OF) ; 



T6963C Dot 



Prototype 


void T6963C dot (int x, int y, unsigned char color); 


Returns 


Nothing. 




Draws a dot in the current graphic panel of GLCD at coordinates (x, y). 




Parameters: 


Description 






- x : dot position on x-axis 




- y: dot position on y-axis 




- color: color parameter. Valid values: T6963C_BLACK and T6963CWHITE 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C_dot (xO, yO, pcolor) ; 
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T6963C write Char 



Prototype 


void T6963C write char (unsigned char c, unsigned char x, unsigned 
char y, unsigned char mode); 


Returns 


Nothing. 


Description 


Writes a char in the current text panel of GLCD at coordinates (x, y). 
Parameters: 

- c : char to be written 

- x : char position on x-axis 

- y: char position on y-axis 

-mode: mode parameter. Valid values: T6963C ROM MODE OR, 
T6963C ROM MODE_XOR, T6963C_ROM_MODE_AND and 
T6963C_ROM_MODE_TEXT 

Mode parameter explanation: 

- OR Mode: In the OR-Mode, text and graphics can be displayed and the data 
is logically "OR-ed". This is the most common way of combining text and 
graphics for example labels on buttons. 

- XOR-Mode: In this mode, the text and graphics data are combined via the 
logical "exclusive OR". This can be useful to display text in the negative 
mode, i.e. white text on black background. - AND-Mode: The text and graph- 
ic data shown on display are combined via the logical "AND function". 

- TEXT-Mode: The text and graphic data shown on display are combined via 
the logical "AND function". 

- TEXT-Mode: This option is only available when displaying just a text. The 
Text Attribute values are stored in the graphic area of display memory. 

For more details see the T6963C datasheet. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C write char ( ' A ' , 22 , 23, AND) ; 
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T6963C write text 



Prototype 


void T6963C write text (unsigned char *str, unsigned char x, 
unsigned char y, unsigned char mode) ; 


Returns 


Nothing. 


Description 


Writes text in the current text panel of GLCD at coordinates (x, y). 
Parameters: 

- str : text to be written 

- x : text position on x-axis 

- y : text position on y-axis 

-mode: mode parameter. Valid values: T6963C ROM MODE_OR, 
T6963C ROM MODE_XOR, T6963C_ROM_MODE_AND and 
T6963C_ROM_MODE_TEXT 

Mode parameter explanation: 

- OR Mode: In the OR-Mode, text and graphics can be displayed and the data 
is logically "OR-ed". This is the most common way of combining text and 
graphics for example labels on buttons. 

- XOR-Mode: In this mode, the text and graphics data are combined via the 
logical "exclusive OR". This can be useful to display text in the negative 
mode, i.e. white text on black background. 

- AND-Mode: The text and graphic data shown on display are combined via 
the logical "AND function". 

- TEXT-Mode: This option is only available when displaying just a text. The 
Text Attribute values are stored in the graphic area of display memory. 

For more details see the T6963C datasheet. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C write text(" Glcd LIBRARY DEMO, WELCOME !", 0, 0, 
T6963C ROM MODE XOR) ; 
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T6963C line 



Prototype 


void T6963C line (int xO, int yO, int xl, int yl, unsigned char 

pcolor ) ; 


Returns 


Nothing. 




Draws a line from (xO, yO) to (x1 , y1 ). 






Parameters: 




Description 


- xO : x coordinate of the line start 

- yO : y coordinate of the line end 

- xi : x coordinate of the line start 

- yi : y coordinate of the line end 

- pcolor : color parameter. Valid values: 
T6963C_BLACK and T6963C_WHITE 




Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_ 


i nit routine. 


Example 


T6963C line(0, 0, 239, 127, T6963C WHITE); 



T6963C_rectangle 



Prototype 


void T6963C rectangle (int xO, int yO, int xl, int yl, unsigned char 

pcolor) ; 


Returns 


Nothing. 


Description 


Draws a rectangle on GLCD. 
Parameters: 

- xO : x coordinate of the upper left rectangle corner 

- yO : y coordinate of the upper left rectangle corner 

- xi : x coordinate of the lower right rectangle corner 

- yi : y coordinate of the lower right rectangle corner 

- pcolor: color parameter. Valid values: T6963C_BLACK and T6963C_WHITE 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C rectangle, 20, 219, 107, T6963C WHITE); 
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T6963C box 



Prototype 


void T6963C box(int xO, int yO, int xl, int yl, unsigned char 

pcolor ) ; 


Returns 


Nothing. 


Description 


Draws a box on GLCD 
Parameters: 

- xO : x coordinate of the upper left box corner 

- yO : y coordinate of the upper left box corner 

- xi : x coordinate of the lower right box corner 

- yi : y coordinate of the lower right box corner 

- pcolor: color parameter. Valid values: T6963C_BLACK and T6963C_WHITE 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C box(0, 119, 239, 127, T6963C WHITE); 



T6963C circle 



Prototype 



void T6963C_circle (int x, int y, long r, unsigned char pcolor) ; 



Returns 



Nothing. 



Description 



Draws a circle on GLCD. 
Parameters: 

- x : x coordinate of the circle center 

- y: y coordinate of the circle center 

- r : radius size 

- pcolor: color parameter. Valid values: T6963C_BLACK and T6963C_WHITE 



Requires 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



Example 



T6963C circle(120, 64, 110, T6963C WHITE); 
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T6963C_image 



Prototype 


void T6963C image (const code char *pic) ; 


Returns 


Nothing. 


Description 


Displays bitmap on GLCD. 
Parameters: 

- pic : image to be displayed. Bitmap array can be located in both code and 
RAM memory (due to the mikroC PRO for PIC pointer to const and pointer to 
RAM equivalency). 

Use the mikroC PRO's integrated Glcd Bitmap Editor (menu option Tools > 
Glcd Bitmap Editor) to convert image to a constant array suitable for display- 
ing on Glcd. 

Note: Image dimension must match the display dimension. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C image (mc) ; 



T6963C_sprite 



Prototype 



Returns 



Description 



Requires 



Example 



void T6963C_sprite (unsigned char px, unsigned char py, const code 
char *pic, unsigned char sx, unsigned char sy) ; 



Nothing. 



Fills graphic rectangle area (px, py) to (px+sx, py+sy) with custom size picture. 
Parameters: 

- px: x coordinate of the upper left picture corner. Valid values: multiples of the 
font width 

- py: y coordinate of the upper left picture corner 

- pic : picture to be displayed 

- sx: picture width. Valid values: multiples of the font width 

- sy: picture height 

Note: If px and sx parameters are not multiples of the font width they will be 
scaled to the nearest lower number that is a multiple of the font width. 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



T6963C_sprite (76, 4, einstein, 88, 119); // draw a sprite 
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T6963C set cursor 



Prototype 



Returns 



Description 



Requires 



void T6963C_set_cursor (unsigned char x, unsigned char y) ; 



Nothing. 



Sets cursor to row x and column y. 
Parameters: 

- x : cursor position row number 

- y: cursor position column number 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



Example T6963C_set_cursor (cposx, cposy) ; 



T6963C clearBit 



Prototype 


void T6963C clearBit (char b) ; 


Returns 


Nothing. 


Description 


Clears control port bit(s). 

Parameters: 

- b : bit mask. The function will clear bit x on control port if bit x in bit mask is set to 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// clear bits and 1 on control port 
T6963C_clearBit (0x03) ; 



T6963C setBit 



Prototype 


void T6963C setBit (char b) ; 


Returns 


Nothing. 


Description 


Sets control port bit(s). 

Parameters: 

- b : bit mask. The function will set bit x on control port if bit x in bit mask is set to 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// set bits and 1 on control port 
T6963C setBit (0x03) ; 
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T6963C_negBit 



Prototype 


void T6963C negBit (char b) ; 


Returns 


Nothing. 


Description 


Negates control port bit(s). 

Parameters: 

- b : bit mask. The function will negate bit x on control port if bit x in bit mask is 
set to 1 . 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// negate bits and 1 on control port 
T6963C_negBit (0x03) ; 



T6963C_displayGrPanel 



Prototype 


void T6963C displayGrPanel (char n) ; 


Returns 


Nothing. 


Description 


Display selected graphic panel. 

Parameters: 

- r. : graphic panel number. Valid values: o and :. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// display graphic panel 1 
T6963C displayGrPanel (1) ; 



T6963C_displayTxtPanel 



Prototype 


void T6963C displayTxtPanel (char n) ; 


Returns 


Nothing. 


Description 


Display selected text panel. 

Parameters: 

- n: text panel number. Valid values: o and l. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// display text panel 1 
T6963C_displayTxtPanel (1) ; 
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T6963C setGrPanel 



Prototype 


void T6963C setTxtPanel (char n) ; 


Returns 


Nothing. 


Description 


Compute start address for selected graphic panel and set appropriate internal pointers. 
All subsequent graphic operations will be preformed at this graphic panel. 

Parameters: 

- n : graphic panel number. Valid values: o and 1. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// set text panel 1 as current text panel. 
T6963C setTxtPanel (1) ; 



T6963C SetTxtPanel 



Prototype 


void T6963C setTxtPanel (char n) ; 


Returns 


Nothing. 


Description 


Compute start address for selected text panel and set appropriate internal point- 
ers. All subsequent text operations will be preformed at this text panel. 

Parameters: 

- n: text panel number. Valid values: o and l. 


Requires 


Toshiba GLCD module needs to be initialized. See the T6963C_lnit routine. 


Example 


// set text panel 1 as current text panel. 
T6963C_setTxtPanel (1) ; 



T6963C PanelFill 



Prototype 



Returns 



Description 



Requires 



Example 



void T6963C_panelFill (unsigned char v) ; 



Nothing. 



Fill current panel in full (graphic+text) with appropriate value (0 to clear). 

Parameters: 

- v: value to fill panel with. 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



//clear current panel 
T6963C_panelFill (0) ; 
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T6963C_grFill 



Prototype 


void T6963C grFill (unsigned char v) ; 


Returns 


Nothing. 


Description 


Fill current graphic panel with appropriate value (0 to clear). 

Parameters: 

- v: value to fill graphic panel with. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// clear current graphic panel 
T6963C grFill (0) ; 



T6963C txtFill 



Prototype 


void T6963C txtFill (unsigned char v) ; 


Returns 


Nothing. 


Description 


Fill current text panel with appropriate value (0 to clear). 

Parameters: 

- v: this value increased by 32 will be used to fill text panel. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// clear current text panel 
T6963C_txtFill (0) ; 



T6963C_cursor_height 



Prototype 


void T6963C cursor height (unsigned char n) ; 


Returns 


Nothing. 


Description 


Set cursor size. 

Parameters: 

- n : cursor height. Valid values: o . . 7. 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


T6963C cursor height (7); 
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T6963C Graphics 



Prototype 



Returns 



Description 



Requires 



Example 



void T6963C_graphics (char n) ; 



Nothing. 



Enable/disable graphic displaying. 

Parameters: 

- n: on/off parameter. Valid values: o (disable graphic dispaying) and : (enable 
graphic displaying). 



Toshiba Glcd module needs to be initialized. See the T6963C init routine. 



// enable graphic displaying 
T6963C_graphics (1) ; 



T6963C text 



Prototype 


void T6963C text (char n) ; 


Returns 


Nothing. 


Description 


Enable/disable text displaying. 
Parameters: 

- n: on/off parameter. Valid values: o (disable text dispaying) and i (enable text 
displaying). 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// enable text displaying 
T6963C_text (1) ; 



T6963C cursor 



Prototype 


void T6963C cursor (char n) ; 


Returns 


Nothing. 


Description 


Set cursor on/off. 

Parameters: 

- n : on/off parameter. Valid values: o (set cursor off) and l (set cursor on). 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// set cursor on 
T6963C_cursor (1) ; 
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T6963C Cursor Blink 



Prototype 


void T6963C cursor blink (char n) ; 


Returns 


Nothing. 


Description 


Enable/disable cursor blinking. 

Parameters: 

- n: on/off parameter. Valid values: o (disable cursor blinking) and i (enable 
cursor blinking). 


Requires 


Toshiba Glcd module needs to be initialized. See the T6963C_init routine. 


Example 


// enable cursor blinking 
T6963C cursor blink (1); 



Library Example 

The following drawing demo tests advanced routines of the T6963C Glcd library. Hardware con- 
figurations in this example are made for the T6963C 240x128 display, EasyPIC5 board and 
16F887. 



#include 



T6963C.h" 



// T6963C module connections 
char T6963C_dataPort at PORTD; 

sbit T6963C_ctrlwr at RC2_bit; 

sbit T6963C_ctrlrd at RClJoit; 

sbit T6963C_ctrlcd at RC0_bit; 

sbit T6963C_ctrlrst at RC4_bit; 

sbit T6963C_ctrlwr_Direction at TRISC2_bit; 

sbit T6963C_ctrlrd_Direction at TRISClJoit; 

sbit T6963C_ctrlcd_Direction at TRISCOJoit; 

sbit T6963C ctrlrst Direction at TRISC4 bit; 



// DATA port 

// WR write signal 

// RD read signal 

// CD command/data signal 

// RST reset signal 

// WR write signal 

// RD read signal 

// CD command/data signal 

// RST reset signal 



// Signals not used by library, they are set in main function 



sbit T6963C_ctrlce at RC3_bit; 
sbit T6963C_ctrlfs at RC6_bit; 
sbit T6963C_ctrlmd at RC5_bit; 
sbit T6963C_ctrlce_Direction at 
sbit T6963C_ctrlfs_Direction 
sbit T6963C ctrlmd Direction 



TRISC3_bit; 
at TRISC6_bit; 
at TRISC5 bit; 



// CE signal 

// FS signal 

// MD signal 

// CE signal direction 

// FS signal direction 

// MD signal direction 



// End T6963C module connections 
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/* 

* bitmap pictures stored in ROM 

*/ 
const code char mC[ ] ; 
const code char einstein[ ] ; 



void main ( ) { 
char txtl[ ] 
char txt[ ] 



EINSTEIN WOULD HAVE LIKED mE' 
GLCD LIBRARY DEMO, WELCOME !' 



unsigned char 
unsigned int 
unsigned char 
unsigned int 

TRISAOJoit = 1 

TRISAlJoit = 1 

TRISA2_bit = 1 

TRISA3_bit = 1 

TRISA4 bit = 1 



panel; 

i ; 

curs ; 

cposx, cposy; 



// Current panel 
// General purpose register 
// Cursor visibility 
// Cursor x-y position 

// Set RAO as input 

// Set RA1 as input 

// Set RA2 as input 

// Set RA3 as input 

// Set RA4 as input 



T6963C ctrlce Direction 



T6963C ctrlce 



0; 



T6963C ctrlfs Direction 



T6963C ctrlfs 



0; 



T6963C ctrlmd Direction 



T6963C ctrlmd 



0; 



// Enable T6963C 

// Font Select 8x8 

// Column number select 



ANSEL = 0; 
ANSELH = 0; 



// Configure AN pins as digital I/O 



// Initialize T6369C 
T6963C init(240, 128, 8); 



/* 



* Enable both graphics and text display at the same time 
*/ 



T6963C_graphics (1) ; 
T6963C_text (1) ; 

panel = 0; 

i = 0; 

curs = ; 

cposx = cposy = ; 

/* 

* Text messages 

*/ 
T6963C_write_text (txt, 0, 0, T6963C_ROM_MODE_XOR) ; 
T6963C write text(txtl, 0, 15, T6963C ROM MODE XOR) 
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/* 



Cursor 



*/ 

T6963C_cursor_height (8) ; 
T6963C_set_cursor (0, ) ; 
T6963C cursor (0) ; 



// 8 pixel height 
// Move cursor to top left 
// Cursor off 



/* 



Draw rectangles 



*/ 

T6963C_rectangle (0, 0, 239, 127, T6963C_WHITE) ; 
T6963C_rectangle (20, 20, 219, 107, T6963C_WHITE ) 
T6963C_rectangle (40, 40, 199, 87, T6963C_WHITE) ; 
T6963C_rectangle (60, 60, 179, 67, T6963C_WHITE) ; 

/* 

* Draw a cross 

*/ 
T6963C_line (0, 0, 239, 127, T6963C_WHITE) ; 
T6963C line(0, 127, 239, 0, T6963C WHITE); 



/* 



Draw solid boxes 



*/ 

T6963C_box(0, 0, 239, 8, T6963C_WHITE) ; 
T6963C box(0, 119, 239, 127, T6963C WHITE) 



/* 



Draw circles 



*/ 

T6963C_circle (120, 64, 10, 

T6963C_circle (120, 64, 30, 

T6963C_circle (120, 64, 50, 

T6963C_circle (120, 64, 70, 

T6963C_circle (120, 64, 90, 

T6963C circle(120, 64, 110, 



T6963C_WHITE) 
T6963C_WHITE) 
T6963C_WHITE) 
T6963C_WHITE) 
T6963C_WHITE) 
T6963C WHITE) 



T6963C_circle (120, 64, 130, T6963C_WHITE) ; 

T6963C_sprite (76, 4, einstein, 88, 119); // Draw a sprite 

T6963C_setGrPanel (1) ; // Select other graphic panel 

T6963C_image (mC) ; 

f or ( ; ; ) { // Endless loop 

/* 

* If RAO is pressed, display only graphic panel 
*/ 
if(RAOJoit) { 

T6963C_graphics (1) ; 
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T6963C_text (0) ; 
Delay_ms (300) ; 
} 

/* 

* If RA1 is pressed, toggle the display between graphic panel 
and graphic panel 1 

*/ 
else if(RAlJoit) { 
panel++; 
panel &= 1 ; 

T6963C_displayGrPanel (panel) ; 
Delay_ms (300) ; 
} 

/* 

* If RA2 is pressed, display only text panel 
*/ 

else if(RA2_bit) { 
T6963C_graphics (0) ; 
T6963C_text (1) ; 
Delay_ms (300) ; 
} 

/* 

* If RA3 is pressed, display text and graphic panels 
*/ 

else if(RA3_bit) { 
T6963C_graphics (1) ; 
T6963C_text (1) ; 
Delay_ms (300) ; 
} 

/* 

* If RA4 is pressed, change cursor 
*/ 

else if(RA4_bit) { 
curs++; 

if (curs == 3) curs = ; 
switch (curs) { 
case : 

// no cursor 
T6963C_cursor (0) ; 
break; 
case 1 : 

// blinking cursor 
T6963C_cursor (1) ; 
T6963C_cursor_blink (1) ; 
break; 
case 2 : 
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// non blinking cursor 
T6963C_cursor (1) ; 
T6963C_cursor_blink (0) ; 
break; 
} 
Delay_ms (300) ; 



/* 

* Move cursor, even if not visible 
*/ 
cposx++; 

if(cposx == T6963C_txtCols) { 
cposx = 0; 
cposy++; 

if(cposy == T6963C_grHeight / T6963C_CHARACTER_HEIGHT) { 
cposy = 0; 



T6963C_set_cursor (cposx, cposy) ; 
Delay_ms (100) ; 
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HW Connection 

Toshiba T6963C Graphic LCD (240x128) 




o- ■ ° r 



vcc 
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T6963C GLCD HW connection 
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UART LIBRARY 

UART hardware module is available with a number of PIC MCUs. mikroC PRO for 
PIC UART Library provides comfortable work with the Asynchronous (full duplex) 
mode. 

You can easily communicate with other devices via RS-232 protocol (for example 
with PC, see the figure at the end of the topic - RS-232 HW connection). You need 
a PIC MCU with hardware integrated UART, for example 16F887. Then, simply use 
the functions listed below. 

Note: Some PIC18 MCUs have multiple UART modules. Switching between the 
UART modules in the UART library is done by the UART_Set_ Active function (UART 
module has to be previously initialized). 

Note: In order to use the desired UART library routine, simply change the number 1 
in the prototype with the appropriate module number, i.e. iiART2_init (2400); 



Library Routines 

- UART1_lnit 

- UART1_Data_Ready 

- UART1_Tx_ldle 

- UART1_Read 

- UART1_Read_Text 

- UART1_Write 

- UART1_Write_Text 

- UART Set Active 
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Uart Init 



Prototype 


void UART1 Init (unsigned long baud rate); 


Returns 


Nothing. 


Description 


Initializes desired hardware UART module with the desired baud rate. Refer to the 
device data sheet for baud rates allowed for specific fosc. If you specify the 
unsupported baud rate, compiler will report an error. 


Requires 


You need PIC MCU with hardware UART. 

uarti init needs to be called before using other functions from UART Library. 

Parameters: 

-baud rate: requested baud rate 

Refer to the device data sheet for baud rates allowed for specific Fosc. 

Note: Calculation of the UART baud rate value is carried out by the compiler, as 
it would produce a relatively large code if performed on the libary level. 
Therefore, compiler needs to know the value of the parameter in the compile time. 
That is why this parameter needs to be a constant, and not a variable. 


Example 


This will initialize hardware UART1 module and establish the communication at 
2400 bps: 

UARTI Init (2400) ; 
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Uart_Data_Ready 



Prototype 


char UART1 Data Ready (); 


Returns 


- l if data is ready for reading 

- o if there is no data in the receive register 


Description 


Use the function to test if data in receive buffer is ready for reading. 


Requires 


UART HW module must be initialized and communication established before 
using this function. See UART1_lnit. 


Example 


// If data is ready, read it: 
if (UART1 Data Ready () == 1 ) { 

receive = UART1 Read(); 

} 



UART1 Tx Idle 



Prototype 


char UART1 Tx Idle(); 


Returns 


- i if data is ready for reading 

- o if there is no data in the receive register 


Description 


Use the function to test if the transmit shift register is empty or not. 


Requires 


UART HW module must be initialized and communication established before 
using this function. See UART1_lnit. 


Example 


// If the previous data has been shifted out, send next data: 
if (UART1 Tx Idle() == 1) { 
UART1 Write ( data) ; 
} 



UART1 Read 



Prototype 


char UART1 Read ( ) ; 


Returns 


Returns the received byte. 


Description 


Function receives a byte via UART. Use the function UARTIDataReady to 
test if data is ready first. 


Requires 


UART HW module must be initialized and communication established before 
using this function. See UART1_lnit. 


Example 


// If data is ready, read it: 
if (UART1 Data Ready () == 1 ) { 

receive = UART1 Read(); 

} 
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UART1 Read Text 



Prototype 


void UART1 Read Text (char *Output, char *Delimiter, char 
Attempts ) ; 


Returns 


Nothing. 


Description 


Reads characters received via UART until the delimiter sequence is detected. 
The read sequence is stored in the parameter output; delimiter sequence is 
stored in the parameter delimiter. 

This is a blocking call: the delimiter sequence is expected, otherwise the proce- 
dure exits (if the delimiter is not found). Parameter Attempts defines number of 
received characters in which Delimiter sequence is expected. If Attempts is set 
to 255, this routine will continuously try to detect the Delimiter sequence. 


Requires 


UART HW module must be initialized and communication established before 
using this function. See UART1_lnit. 


Example 


Read text until the sequence "OK" is received, and send back what' s 
been received: 

UART1 Init(4800); // initialize UART1 module 
Delay ms (100) ; 

while (1) { 

if (UART1 Data Ready () == 1) { // if data is received 

UART1 Read Text(output, "delim", 10); // reads text until 
'delim' is found 

UART1 Write Text (output) ; // sends back text 
} 



UART1 Write 



Prototype 


void UART1 Write (char data); 


Returns 


Nothing. 


Description 


The function transmits a byte via the UART module. 

Parameters: 
data: data to be sent 


Requires 


UART HW module must be initialized and communication established before 
using this function. See UART1_lnit. 


Example 


unsigned char data = OxlE; 
UART1 Write ( data) ; 
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UART1 Write Text 



Prototype 


void UART1 Write Text (char * UART text); 


Returns 


Nothing. 


Description 


Sends text (parameter UARTtext) via UART. Text should be zero terminated. 


Requires 


UART HW module must be initialized and communication established before 


using this function. See UART1_lnit. 




Read text until the sequence "OK" is received, and send back 




what' s been received: 




UART1 lnit(4800); // initialize UART1 module 




Delay ms (100) ; 


Example 


while (1) { 




if (UART1 Data Ready () == 1) { // if data is received 




UART1 Read Text (output, "delim", 10); // reads text until 




'delim' is found 




UART1 Write Text (output ) ; // sends back text 
} 



UART Set Active 



Prototype 


void UART Set Active (char (*read ptr) (), void 
(*write ptr) (unsigned char data ), char (ready ptr) (), char 
(*tx idle ptr) () ) 


Returns 


Nothing. 


Description 


Sets active UART module which will be used by the UART library routines. 
Parameters: 

- read ptr: UART1_Read handler 
-write ptr: UART1_Write handler 

- ready ptr: UART1_Data_Ready handler 

- tx idle ptr: UART1_Tx_ldle handler 


Requires 


Routine is available only for MCUs with two UART modules. 

Used UART module must be initialized before using this routine. See 
UART1_lnit routine 


Example 


// Activate UART2 module 

UART Set Active (SUART1 Read, SUART1 Write, SUART1 Data Ready, 

&UART1 Tx Idle) ; 
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Library Example 

The example demonstrates a simple data exchange via UART When PIC MCU 
receives data, it immediately sends it back. If PIC is connected to the PC (see the 
figure below), you can test the example from the mikroC PRO for PIC terminal for 
RS-232 communication, menu choice Tools > Terminal. 



char uart_rd; 
void main ( ) { 

UARTl_Init (9600) ; 
bps 

Delayjns (100) ; 
lize 



// Initialize UART module at 9600 
// Wait for UART module to stabi- 



while (1) { 

if (UARTl_Data_Ready () ) { 
uart_rd = UARTl_Read ( ) ; 
UART1 Write (uart rd) ; 



// Endless loop 

// If data is received, 

// read the received data, 

// and send data via UART 
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HW Connection 



RS-232 
CON 



SERIAL 






RS-232 
CON 




RS-232 HW connection 
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USB HID LIBRARY 

Universal Serial Bus (USB) provides a serial bus standard for connecting a wide 
variety of devices, including computers, cell phones, game consoles, PDA's, etc. 

mikroC PRO for PIC includes a library for working with human interface devices via 
Universal Serial Bus. A human interface device or HID is a type of computer device 
that interacts directly with and takes input from humans, such as the keyboard, 
mouse, graphics tablet, and the like. 

Descriptor File 

Each project based on the USB HID library should include a descriptor source file 
which contains vendor id and name, product id and name, report length, and other 
relevant information. To create a descriptor file, use the integrated USB HID termi- 
nal of mikroC PRO for PIC(Tools > USB HID Terminal). The default name for 

descriptor file is usBdsc . c, but you may rename it. 

The provided code in the "Examples" folder works at 48MHz, and the flags should 
not be modified without consulting the appropriate datasheet first. 

Library Routines 

- Hid_Enable 

- Hid_Read 

- Hid_Write 

- Hid Disable 
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Hid Enable 



Prototype 


void Hid Enable (unsigned readbuff, unsigned writebuff); 


Returns 


Nothing. 


Description 


Enables USB HID communication. Parameters readbuff and writebuff are 
the Read Buffer and the Write Buffer, respectively, which are used for HID com- 
munication. 

This function needs to be called before using other routines of USB HID Library. 


Requires 


Nothing. 


Example 


Hid Enable (&rd, Swr) ; 



Hid Read 



Prototype 



unsigned char Hid_Read (void) ; 



Returns 



Number of characters in the Read Buffer received from the host. 



Description 



Receives message from host and stores it in the Read Buffer. Function returns 
the number of characters received in the Read Buffer. 



Requires 



USB HID needs to be enabled before using this function. See Hid_Enable. 



Example 



get 



Hid Read() ; 



Hid Write 



Prototype 



unsigned short HidWrite (unsigned writebuff, unsigned short len) 



Returns 



1 if data was successfuly sent, if not. 



Description 



Function sends data from Write Buffer writebuff to host. Write Buffer is the 
same parameter as used in initialization; see Hid_Enable. Parameter len 
should specify a length of the data to be transmitted. 

Function call needs to be repeated as long as data is not successfuly sent. 



Requires 



USB HID needs to be enabled before using this function. See Hid_Enable. 



Example 



// retry until success. 

while ( !Hid_Write (Smy_Usb_Buf f , 1 ) ) ; 
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Hid Disable 



Prototype 


void Hid Disable (void) ; 


Returns 


Nothing. 


Description 


Disables USB HID communication. 


Requires 


USB HID needs to be enabled before using this function. See Hid_Enable. 


Example 


Hid Disable () ; 



Library Example 

The following example continually sends sequence of numbers 0..255 to the PC via Universal Ser- 
ial Bus. usbdsc.c must be included in the project (via mikroC PRO for PIC IDE tool or via 
#inciude mechanism in source code). 

unsigned short m, k; 

unsigned short userRD_buf fer[ 64] ; 
unsigned short userWR_buf fer[ 64] ; 

void interrupt () { 

asm CALL Hid InterruptProc 

asm nop 
} 



void Init Main ( ) { 

// Disable all interrupts 

// Disable GIE, PEIE, TMROIE, INTOIE,RBIE 

INTCON = 0; 

INTCON2 = 0xF5; 

INTCON3 = OxCO; 

// Disable Priority Levels on interrupts 

RCON.IPEN = 0; 

PIE1 = 0; 

PIE2 = 

PIR1 = 

PIR2 = 



// Configure all ports with analog function as digital 
ADCON1 |= OxOF; 



// Ports Configuration 

TRISA = 0; 

TRISB = 0; 

TRISC = OxFF; 

TRISD = OxFF; 

TRISE = 0x07; 
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LATA = 




LATB = 




LATC = 




LATD = 




LATE = 




// Clear 


user RAM 


// Banks 


[ 00 . . 07] ( 


asm { 




LFSR 


FSRO, 0x000 


MOVLW 


0x08 


CLRF 


POSTINC0, 


CPFSEQ 


FSR0H, 


BRA 


$ - 2 



x 256 = 2048 Bytes ) 



// Timer 

T0CON = 0x07; 

TMR0H = (65536-156) » 8; 

TMR0L = (65536-156) S OxFF; 

INTCON.T0IE = 1; 

T0CON.TMR0ON = 1 ; 



// Enable T0IE 



/** Main Program Routine **/ 

void main ( ) { 
Init_Main () ; 
Hid_Enable ( &userRD_buf f er , &userWR_buf fer) ; 

do { 

for (k = 0; k < 255; k++) { 
// Prepare send buffer 
userWR_buf fer[ 0] = k; 

// Send the number via USB 
Hid_Write (suserWRJouf fer, 1) ; 
} 
} while ( 1 ) ; 

Hid Disable () ; 
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HW Connection 





USB connection scheme 
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STANDARD ANSI C LIBRARIES 

-ANSI C Ctype Library 
-ANSI C Math Library 
-ANSI CStdlib Library 
-ANSI C String Library 

ANSI C Ctype Library 

The mikroC PRO for PIC provides a set of standard ANSI C library functions for test- 
ing and mapping characters. 

Note: Not all of the standard functions have been included. 

Note: The functions have been mostly implemented according to the ANSI C stan- 
dard, but certain functions have been modified in order to facilitate PIC program- 
ming. Be sure to skim through the description before using standard C functions. 

Library Functions 

- isalnum 

- isalpha 

- iscntrl 

- isdigit 

- isgraph 

- islower 

- ispunct 

- isspace 

- isupper 

- isxdigit 

- toupper 

- tolower 
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isalnum 



Prototype 



Description 



unsigned short isalpha (char character); 



Function returns 1 if the character is alphanumeric (A-Z, a-z, 0-9), otherwise 
returns zero. 



isalpha 



Prototype 



Description 



unsigned short isalpha (char character); 



Function returns 1 if the character is alphabetic (A-Z, a-z), otherwise returns 
zero. 



iscntrl 



Prototype 



Description 



unsigned short iscntrl (char character) 



Function returns 1 if the character is a control or delete character(decimal 0- 
31 and 127), otherwise returns zero. 



isdigit 



Prototype 



Description 



unsigned short isdigit (char character) 



Function returns 1 if the character is a digit (0-9), otherwise returns zero. 



isgraph 



Prototype 



Description 



unsigned short isgraph (char character); 



Function returns 1 if the character is a printable, excluding the space (decimal 
32), otherwise returns zero. 



islower 



Prototype 



Description 



int islower (char character); 



Function returns 1 if the character is a lowercase letter (a-z), otherwise returns 
zero. 



ispunct 



Prototype 



Description 



unsigned short ispunct (char character); 



Function returns 1 if the character is a punctuation (decimal 32-47, 58-63, 91- 
96, 123-126), otherwise returns zero. 
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isspace 



Prototype 



Description 



unsigned short isspace (char character); 



Function returns 1 if the character is a white space (space, tab, CR, HT, VT, 
NL, FF), otherwise returns zero. 



isupper 



Prototype 



unsigned short isupper (char character); 



Description 



Function returns 1 if the character is an uppercase letter (A-Z), otherwise 
returns zero. 



isxdigit 




Prototype 


unsigned short isxdigit (char character) ; 


Description 


Function returns 1 if the character is a hex digit (0-9, A-F, a-f), otherwise 
returns zero. 



toupper 



Prototype 



unsigned short toupper (char character) 



Description 



If the character is a lowercase letter (a-z), the function returns an uppercase 
letter. Otherwise, the function returns an unchanged input parameter. 



tolower 



Prototype 



unsigned short tolower (char character) 



Description 



If the character is an uppercase letter (A-Z), function returns a lowercase let- 
ter. Otherwise, function returns an unchanged input parameter. 
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ANSI C Math Library 

The mikroC PRO for PIC provides a set of standard ANSI C library functions for 
floating point math handling. 

Note: Not all of the standard functions have been included. 

Note: The functions have been mostly implemented according to the ANSI C stan- 
dard, but certain functions have been modified in order to facilitate PIC program- 
ming. Be sure to skim through the description before using standard C functions. 

Library Functions 

- acos 

- asin 

- atan 

- atan2 

- ceil 

- cos 

- cosh 

- eval_poly 

- exp 

- fabs 

- floor 

- frexp 

- Idexp 

- log 

- log 10 

- modf 

- pow 

- sin 

- sinh 

- sqrt 

- tan 

- tanh 
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acos 



Prototype 



double acos (double x) ; 



Description 



Function returns the arc cosine of parameter x; that is, the value whose cosine 
is x. The input parameter x must be between -1 and 1 (inclusive). The return 
value is in radians, between and n (inclusive). 



asin 



Prototype 



double asin (double x) ; 



Description 



Function returns the arc sine of parameter x; that is, the value whose sine is x. 
The input parameter : must be between -1 and 1 (inclusive). The return value is 
in radians, between -n/2 and n/2 (inclusive). 



atan 



Prototype 



double atan (double f) 



Description 



Function computes the arc tangent of parameter f; that is, the value whose tan- 
gent is f . The return value is in radians, between -n/2 and n/2 (inclusive). 



atan2 



Prototype 



double atan2 (double y, double x) 



This is the two-argument arc tangent function. It is similar to computing the arc 
tangent of y/x, except that the signs of both arguments are used to determine 
the quadrant of the result and x is permitted to be zero. The return value is in 
radians, between -n and n (inclusive). 



Description 



ceil 



Prototype 



double ceil (double x) ; 



Description 



Function returns value of parameter x rounded up to the next whole number. 



cos 



Prototype 


double cos (double f ) ; 


Description 


Function returns the cosine of r in radians. The return value is from -1 to 1 . 
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cosh 



Prototype 



Description 



double cosh (double x) ; 



Function returns the hyperbolic cosine of::, defined mathematically as (e x +e~ x ) 12. If 
the value of x is too large (if overflow occurs), the function fails. 



eval_poly 



Prototype 



Description 



static double evalpoly (double x, const double code * d, int n) 



Function Calculates polynom for number x, with coefficients stored in d[ i , for 
degree n. 



exp 








Prototype 


double exp (double x) ; 


Description 


Function returns the value of e - 

power x (i.e. ex). 


- the base of natural logarithms - 


- raised to the 



fabs 






Prototype 


double fabs (double d) ; 


Description 


Function returns the absolute (i.e. 


positive) value of d. 



floor 




Prototype 


double floor (double x) ; 


Description 


Function returns the value of parameter x rounded down to the nearest integer. 



frexp 



Prototype 



double frexp (double value, int *eptr); 



Description 



Function splits a floating-point value into a normalized fraction and an integral 
power of 2. The return value is the normalized fraction and the integer exponent 
is stored in the object pointed to by eptr. 



Idexp 



Prototype 



double ldexp (double value, int newexp) 



Description 



Function returns the result of multiplying the floating-point number num by 2 
raised to the power r. (i.e. returns x * 2n). 
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log 






Prototype 


double log (double x) ; 


Description 


Function returns the natural logarithm of x (i.e. loge 


(X)). 



Iog10 



Prototype 



Description 



double log 10 (double x) ; 



Function returns the base-10 logarithm of x (i.e. logio (x)). 



modf 



Prototype 



Description 



double modf (double val, double * iptr); 



Returns argument val split to the fractional part (function return val) and integer 
part (in number iptr). 



pow 



Prototype 



double pow (double x, double y) 



Description 



Function returns the value of x raised to the power y (i.e. xy). If x is negative, 
the function will automatically cast y into unsigned long. 



sin 




Prototype 


double sin (double f ) ; 


Description 


Function returns the sine of f in radians. The return value is from -1 to 1. 



sinh 



Prototype 



double sinh (double x) 



Description 



Function returns the hyperbolic sine of x, defined mathematically as (ex-e- 
x) 12. If the value of x is too large (if overflow occurs), the function fails. 



sqrt 



Prototype 



double sqrt (double x) ; 



Description 



Function returns the non negative square root of 
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tan 



Prototype 



Description 



double tan (double x) 



Function returns the tangent of x in radians. The return value spans the 
allowed range of floating point in the mikroC PRO for PIC. 



tanh 



Prototype 



Description 



double tanh (double x) ; 



Function returns the hyperbolic tangent of x, defined mathematically as 

sinh (x) /cosh (x) . 



ANSI C Stdlib Library 

The mikroC PRO for PIC provides a set of standard ANSI C library functions of general utility. 

Note: Not all of the standard functions have been included. 

Note: Functions have been mostly implemented according to the ANSI C standard, but certain 
functions have been modified in order to facilitate PIC programming. Be sure to skim through the 
description before using standard C functions. 

Library Functions 

- abs 
-atof 

- atoi 
-atol 

- div 
-Idiv 

- uldiv 

- labs 

- max 

- min 

- rand 

- srand 

- xtoi 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 571 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



abs 



Prototype 



Description 



int abs (int a) ; 



Function returns the absolute (i.e. positive) value of 



atof 



Prototype 



Description 



double atof (char 



Function converts the input string s into a double precision value and returns the 
value. Input string s should conform to the floating point literal format, with an 
optional whitespace at the beginning. The string will be processed one character 
at a time, until the function reaches a character which it doesn't recognize (includ- 
ing a null character). 



atoi 



Prototype 



Description 



int atoi (char 



Function converts the input string s into an integer value and returns the value. 
The input string s should consist exclusively of decimal digits, with an optional 
whitespace and a sign at the beginning. The string will be processed one charac- 
ter at a time, until the function reaches a character which it doesn't recognize 
(including a null character). 



atoi 



Prototype 



Description 



long atoi (char *s) 



Function converts the input string s into a long integer value and returns the 
value. The input string s should consist exclusively of decimal digits, with an 
optional whitespace and a sign at the beginning. The string will be processed one 
character at a time, until the function reaches a character which it doesn't recog- 
nize (including a null character). 



div 



Prototype 



Description 



div t div (int number, int denom) 



Function computes the result of division of the numerator number by the denom- 
inator denom; the function returns a structure of type div t comprising quotient 
(quot) and remainder (rem), see Div Structures. 
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Idiv 



Prototype 



Description 



ldiv_t ldiv (long number, long denom); 



Function is similar to the div function, except that the arguments and result 
structure members all have type long. 

Function computes the result of division of the numerator number by the denom- 
inator denom; the function returns a structure of type idiv t comprising quo- 
tient (quot) and remainder (rem), see Div Structures. 



uldiv 



Prototype 



Description 



uldiv_t uldiv (unsigned long number, unsigned long denom); 



Function is similar to the div function, except that the arguments and result 
structure members all have type unsigned long. 

Function computes the result of division of the numerator number by the denom- 
inator denom; the function returns a structure of type uldiv t comprising quo- 
tient (quot) and remainder (rem), see Div Structures. 



labs 




Prototype 


long labs (long x) ; 


Description 


Function returns the absolute (i.e. positive) value of long integer x. 



max 



Prototype 



Description 



int max(int a, int b) ; 



Function returns greater of the two integers, a and 



mm 



Prototype 



int min(int a, int b) ; 



Description 



Function returns lower of the two integers, a and b. 



rand 



Prototype 



int rand ( ) 



Description 



Function returns a sequence of pseudo-random numbers between and 32767. 
The function will always produce the same sequence of numbers unless srand 
is called to seed the start point. 
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srand 



Prototype 



Description 



void srand (unsigned x) ; 



Function uses > as a starting point for a new sequence of pseudo-random num- 
bers to be returned by subsequent calls to rand. No values are returned by this 
function. 



xtoi 



Prototype 



Description 



unsigned xtoi (register char *s) 



Function converts the input string s consisting of hexadecimal digits into an inte- 
ger value. The input parameter s should consist exclusively of hexadecimal dig- 
its, with an optional whitespace and a sign at the beginning. The string will be 
processed one character at a time, until the function reaches a character which it 
doesn't recognize (including a null character). 



Div Structures 

typedef struct divstruct 
int quot; 
int rem; 

} div t; 



typedef struct ldivstruct { 
long quot; 
long rem; 

} ldiv t; 



typedef struct uldivstruct { 

unsigned long quot; 
unsigned long rem; 

} uldiv t; 
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ANSI C String Library 

The mikroC PRO for PIC provides a set of standard ANSI C library functions useful 
for manipulating strings and RAM memory. 

Note: Not all of the standard functions have been included. 

Note: Functions have been mostly implemented according to the ANSI C standard, 
but certain functions have been modified in order to facilitate PIC programming. Be 
sure to skim through the description before using standard C functions. 

Library Functions 

- memchr 

- memcmp 

- memcpy 

- memmove 

- memset 

- strcat 

- strchr 

- strcmp 

- strcpy 

- strlen 

- strncat 

- strncpy 

- strspn 

- strncmp 

- strstr 

- strcspn 

- strpbrk 

- strrchr 
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memchr 



Prototype 



Description 



void * memchr (void *p, char n, unsigned int 



Function locates the first occurrence of r. in the initial > bytes of memory area 
starting at the address p. The function returns the pointer to this location or o if 
the n was not found. 

For parameter p you can use either a numerical value (literal/variable/constant) 
indicating memory address or a dereferenced value of an object, for example 

Smystring Of SPO. 



memcmp 



Prototype 



Description 



int memcmp (void *sl, void *s2, int n) 



Function compares the first n characters of objects pointed to by si and s2 and 
returns zero if the objects are equal, or returns a difference between the first dif- 
fering characters (in a left-to-right evaluation). 

Accordingly, the result is greater than zero if the object pointed to by si is greater 
than the object pointed to by s2 and vice versa. 



memcpy 



Prototype 



Description 



void * memcpy (void *dl, void *sl, int n) ; 



Function copies r characters from the object pointed to by si into the object point- 
ed to by dl. If copying takes place between objects that overlap, the behavior is 
undefined. The function returns address of the object pointed to by di. 



memmove 



Prototype 



Description 



void * memmove (void *to, void * f rom, register int n) 



Function copies n characters from the object pointed to by from into the object 
pointed to by to. Unlike memcpy, the memory areas to and from may overlap. 
The function returns address of the object pointed to by to. 



memset 



Prototype 



void *memset(void *pl, char character, int n) 



Description 



Function copies the value of the character into each of the first r characters of 
the object pointed by pi. The function returns address of the object pointed to 
by pi. 
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strcat 



Prototype 



Description 



char * strcat (char *to, char * f rom) 



Function appends a copy of the string from to the string to, overwriting the null 
character at the end of to. Then, a terminating null character is added to the 
result. If copying takes place between objects that overlap, the behavior is unde- 
fined, to string must have enough space to store the result. The function returns 
address of the object pointed to by to. 



strchr 



Prototype 



Description 



char * strchr (char *ptr, char chr); 



Function locates the first occurrence of character chr in the string ptr. The func- 
tion returns a pointer to the first occurrence of character chr, or a null pointer if 
chr does not occur in ptr. The terminating null character is considered to be a 
part of the string. 



strcmp 



Prototype 



Description 



int strcmp (char *sl, char *s2) 



Function compares strings si and s2 and returns zero if the strings are equal, or 
returns a difference between the first differing characters (in a left-to-right evalu- 
ation). Accordingly, the result is greater than zero if si is greater than s2 and vice 
versa. 



strcpy 



Prototype 



Description 



char * strcpy (char *to, char * f rom) 



Function copies the string from into the string to. If copying is successful, the 
function returns to. If copying takes place between objects that overlap, the 
behavior is undefined. 



strlen 



Prototype 



Description 



int strlen (char *s) 



Function returns the length of the string s (the terminating null character does not 
count against string's length). 
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strncat 



Prototype 



Description 



char * strncat (char *to, char * f rom, int size) 



Function appends not more than size characters from the string from to to. The 
initial character of from overwrites the null character at the end of to. The termi- 
nating null character is always appended to the result. The function returns to. 



strncpy 



Prototype 



char * strncpy (char *to, char * f rom, int size) 



Description 



Function copies not more than size characters from string from to to. If copy- 
ing takes place between objects that overlap, the behavior is undefined. If from 
is shorter than size characters, then to will be padded out with null characters to 
make up the difference. The function returns the resulting string to. 



strspn 



Prototype 



int strspn (char *strl, char *str2) 



Function returns the length of the maximum initial segment of stri which consists 
entirely of characters from str2. The terminating null character at the end of the 
string is not compared. 



Description 



strncmp 



Prototype 



int strncmp(char *sl, char *s2, char len) 



Description 



Function lexicographically compares not more than len characters (characters 
that follow the null character are not compared) from the string pointed by si to 
the string pointed by s2. The function returns a value indicating the si and s2 
relationship: 

Value Meaning 

< si "less than" s2 

= si "equal to" s2 

> si "greater than" s2 
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strstr 



Prototype 



Description 



char * strstr (char *sl, char *s2); 



Function locates the first occurrence of the string s2 in the string si (excluding 
the terminating null character). 

The function returns pointer to first occurrence of s2 in si; if no string was found, 
function returns o. If s2 is a null string, the function returns o. 



strcspn 



Prototype 



Description 



char * strcspn (char * si, char *s2); 



Function computes the length of the maximum initial segment of the string point- 
ed to by si that consists entirely of characters that are not in the string pointed 
to by s2. 

The function returns the length of the initial segment. 



strpbrk 



Prototype 



char * strpbrk (char * si, char *s2) 



Description 



Function searches si for the first occurrence of any character from the string s2. 
The terminating null character is not included in the search. The function returns 
pointer to the matching character in si. If si contains no characters from s2, the 
function returns o. 



strrchr 



Prototype 



char * strrchr (char * ptr, unsigned int chr) 



Description 



Function searches the string ptr for the last occurrence of character chr . The 
null character terminating ptr is not included in the search. The function returns 
pointer to the last chr found in ptr; if no matching character was found, function 
returns o. 
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MISCELLANEOUS LIBRARIES 

- Button Library 

- Conversions Library 

- Sprint Library 

- Setjmp Library 

- Time Library 

- Trigonometry Library 
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BUTTON LIBRARY 

The Button library contains miscellaneous routines useful for a project development. 
Library Routines 

- Button 
Button 



Prototype 


unsigned short Button (unsigned short *port, unsigned short pin, 
unsigned short time, unsigned short active state); 


Returns 


Returns or 255. 


Description 


Function eliminates the influence of contact flickering upon pressing a button 
(debouncing). 

Parameter port specifies the location of the button; parameter pin is the pin 
number on designated port and goes from 0..7; parameter time is a debounce 
period in milliseconds; parameter active state can be either or 1 , and it deter- 
mines if the button is active upon logical zero or logical one. 


Requires 


Button pin must be configured as input. 


Example 


Example reads RBO, to which the button is connected; on transition from 1 to 
(release of button), PORTD is inverted: 

do { 

if (Button (&PORTB, 0, 1, 1)) oldstate = 1; 
if (oldstate && Button (&PORTB, 0, 1, 0)) { 

PORTD = -PORTD; 

oldstate = 0; 
} 
} while ( 1 ) ; 
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CONVERSIONS LIBRARY 

The mikroC PRO for PIC Conversions Library provides routines for numerals to 
strings and BCD/decimal conversions. 

Library Routines 

You can get text representation of numerical value by passing it to one of the follow- 
ing routines: 

- ByteToStr 

- ShortToStr 

- WordToStr 

- IntToStr 

- LongToStr 

- LongWordToStr 

- FloatToStr 

The following functions convert decimal values to BCD and vice versa: 

- Dec2Bcd 

- Bcd2Dec16 

- Dec2Bcd16 
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ByteToStr 



Prototype 


void ByteToStr (unsigned short input, char *output); 


Returns 


Nothing. 




Converts input byte to a string. The output string has fixed width of 4 characters 




including null character at the end (string termination). The output string is right 




justified and remaining positions on the left (if any) are filled with blanks. 


Description 


Parameters: 




- input : byte to be converted 




- output: destination string 


Requires 


Destination string should be at least 4 characters in length. 




unsigned short t = 2 4; 


Example 


char txt[ 4] ; 




ByteToStr (t, txt); // txt is " 24" (one blank here) 



ShortToStr 



Prototype 


void ShortToStr (short input, char *output); 


Returns 


Nothing. 


Description 


Converts input signed short number to a string. The output string has fixed width 
of 5 characters including null character at the end (string termination). The output 
string is right justified and remaining positions on the left (if any) are filled with 
blanks. 

Parameters: 

- input : short number to be converted 

- output: destination string 


Requires 


Destination string should be at least 5 characters in length. 


Example 


short t = -24; 
char txt[ 5] ; 

ShortToStr (t, txt); // txt is " -24" (one blank here) 
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WordToStr 



Prototype 


void WordToStr (unsigned input, char *output); 


Returns 


Nothing. 




Converts input word to a string. The output string has fixed width of 6 characters 




including null character at the end (string termination). The output string is right 




justified and the remaining positions on the left (if any) are filled with blanks. 


Description 


Parameters: 




- input : word to be converted 




- output: destination string 


Requires 


Destination string should be at least 6 characters in length. 




unsigned t = 4 37; 


Example 


char txt[ 6] ; 




WordToStr (t, txt); // txt is " 437" (two blanks here) 



IntToStr 



Prototype 


void IntToStr (int input, char *output); 


Returns 


Nothing. 


Description 


Converts input signed integer number to a string. The output string has fixed width 
of 7 characters including null character at the end (string termination). The output 
string is right justified and the remaining positions on the left (if any) are filled with 
blanks. 

Parameters: 

- input : signed integer number to be converted 

- output: destination string 


Requires 


Destination string should be at least 7 characters in length. 


Example 


int j = -4220; 
char txt[ 7] ; 

IntToStr (j, txt); // txt is " -4220" (one blank here) 
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LongintToStr 



Prototype 


void LongToStr (long input, char *output); 


Returns 


Nothing. 


Description 


Converts input signed long integer number to a string. The output string has fixed 
width of 12 characters including null character at the end (string termination). The 
output string is right justified and the remaining positions on the left (if any) are 
filled with blanks. 

Parameters: 

- input : signed long integer number to be converted 

- output: destination string 


Requires 


Destination string should be at least 12 characters in length. 


Example 


long jj = -3700000; 
char txt[ 12] ; 

LongToStr ( j j , txt) ; 

// txt is " -3700000" (three blanks here) 



LongWordToStr 



Prototype 


void LongWordToStr (unsigned long input, char * output); 


Returns 


Nothing. 


Description 


Converts input unsigned long integer number to a string. The output string has 
fixed width of 11 characters including null character at the end (string termination). 
The output string is right justified and the remaining positions on the left (if any) 
are filled with blanks. 

Parameters: 

- input : unsigned long integer number to be converted 

- output: destination string 


Requires 


Destination string should be at least 11 characters in length. 


Example 


unsigned long jj = 3700000; 
char txt[ 11] ; 

LongToStr ( j j , txt) ; 

// txt is " 3700000" (three blanks here) 
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FloatToStr 



Prototype 



Returns 



Description 



Requires 



Example 



unsigned char FloatToStr (float fnum, unsigned char *str) 



3 if input number is NaN 
2 if input number is -INF 
1 if input number is +INF 
if conversion was successful 



Converts a floating point number to a string. 
Parameters: 

- input : floating point number to be converted 

- output: destination string 

The output string is left justified and null terminated after the last digit. 

Note: Given floating point number will be truncated to 7 most significant digits 
before conversion. 



Destination string should be at least 14 characters in length. 



float ffl = -374.2; 
float ff2 = 123.456789; 
float ff3 = 0.000001234; 
char txt[ 15] ; 



FloatToStr (ffl, txt) 
FloatToStr (ff2, txt) 
FloatToStr (ff3, txt) 



// txt is "-374.2" 
// txt is "123.4567' 
// txt is "1.234e-6' 
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Dec2Bcd 



Prototype 


unsigned short Dec2 Bed (unsigned short decnum); 


Returns 


Converted BCD value. 




Converts input unsigned short integer number to its appropriate BCD 


represen- 




tation. 




Description 


Parameters: 

- decnum: unsigned short integer number to be converted 




Requires 


Nothing. 




unsigned short a, b; 




Example 


a = 22; 

b = Dec2Bcd(a); // b equals 34 





Bcd2Dec16 



Prototype 


unsigned Bcd2Decl6 (unsigned bednum) ; 


Returns 


Converted decimal value. 


Description 


Converts 16-bit BCD numeral to its decimal equivalent. 

Parameters: 

- bednum: 16-bit BCD numeral to be converted 


Requires 


Nothing. 


Example 


unsigned a, b; 

a = 0x1234; // a equals 4660 
b = Bcd2Decl6 (a) ; // b equals 1234 
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Dec2Bcd16 



Prototype 


unsigned Dec2Bcdl6 (unsigned decnum) ; 


Returns 


Converted BCD value. 




Converts unsigned 16-bit decimal value to its BCD equivalent. 


Description 


Parameters: 




- decnum unsigned 16-bit decimal number to be converted 


Requires 


Nothing. 




unsigned a, b; 


Example 


a = 2345; 




b = Dec2Bcdl6 (a) ; // b equals 9029 
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PRINTOUT LIBRARY 

The mikroC PRO for PIC provides the Printout routine for easy data formatting and printing. 
Note: Library works with PIC18 family only. 
Library Routines 

- Printout 
Printout 



Prototype 



Returns 



Description 



void Printout (void (*prntoutf unc) (char ch) , const char *£,...] 



Nothing. 



Printout is used to format data and print them in a way defined by the user 
through a print handler function. 

Parameters: 

- prntoutfunc: print handler function 

- f :format string 

The f argument is a format string and may be composed of characters, escape 
sequences, and format specifications. Ordinary characters and escape 
sequences are copied to the print handler in order in which they are interpreted. 
Format specifications always begin with a percent sign ( ) and require additional 
arguments to be included in the function call. 

The format string is read from left to right. The first format specification encoun- 
tered refers to the first argument after the f parameter and then converts and out- 
puts it using the format specification. The second format specification accesses 
the second argument after r, and so on. If there are more arguments than format 
specifications, the extra arguments are ignored. Results are unpredictable if there 
are not enough arguments for the format specifications. The format specifications 
have the following format: 

% [ flags] [width] [ .precision] [{ 1 | L }] conversion_type 

Each field in the format specification can be a single character or a number which 
specifies a particular format option. The conversiontype field is where a single 
character specifies that an argument is interpreted as a character, string, number, 
or pointer, as shown in the following table: 
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conversion type 


Argument Type 


Output Format 


d 


int 


Signed decimal number 


u 


unsigned int 


Unsigned decimal number 





unsigned int 


Unsigned octal number 


X 


unsigned int 


Unsigned hexadecimal number using 
0123456789abcdef 


X 


unsigned int 


Unsigned hexadecimal number using 
0123456789ABCEDF 


f 


double 


Floating-point number using the format [- 
Idddd.dddd 


e 


double 


Floating-point number using the format [- 
|d.dddde[-]dd 


E 


double 


Floating-point number using the format [- 
|d.ddddE[-]dd 


g 


double 


Floating-point number using either e orf 
format, whichever is more compact for the 
specified value and precision 


c 


int 


int is Converted to an unsigned char, 

and the resulting character is written 


s 


char * 


String with a terminating null character 


p 


void * 


Pointer value, the X format is used 


% 


<none> 


A % is written. No argument is converted. 
The complete conversion specification 
shall be %%. 
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The flags field is where a single character is used to justify the output and to 
print +/- signs and blanks, decimal points, and octal and hexadecimal prefixes, as 
shown in the following table. 



flags 


Meaning 


+ 


Left justify the output in the specified field width. 




Prefix the output value with + or - sign if the output is a signed type. 


space 
(' ') 


Prefix the output value with a blank if it is a signed positive value. 
Otherwise, no blank is prefixed. 


# 


Prefix a non-zero output value with o ]x, or ox when used with o 
and x field types, respectively. When used with the e, e, f , g, and g 
field types, the # flag forces the output value to include a decimal 
point. In any other case the i flag is ignored. 




Ignore format specifier. 



The width field is a non-negative number that specifies a minimum number of 
printed characters. If a number of characters in the output value is less than width, 
blanks are added on the left or right (when the - flag is specified) in order to pad 
to the minimum width. If the width is prefixed with 0, then zeros are padded 
instead of blanks. The width field never truncates a field. If the length of the out- 
put value exceeds the specified width, all characters are output. 

The precision field is a non-negative number that specifies the number of char- 
acters to print, number of significant digits, or number of decimal places. The pre- 
cision field can cause truncation or rounding of the output value in the case of a 
floating-point number as specified in the following table. 



flags 


MeaningMeaning of the precision field 


d, u, o, 
x, X 


The precision field is where you specify the minimum number of 
digits that will be included in the output value. Digits are not trun- 
cated if the number of digits in an argument exceeds that defined 
in the precision field. If the number of digits in the argument is 
less than the precision field, the output value is padded on the 
left with zeros. 


f 


The precision field is where you specify the number of digits to 
the right of the decimal point. The last digit is rounded. 


e, E 


The precision field is where you specify the number of digits to 
the right of the decimal point. The last digit is rounded. 


g 


The precision field is where you specify the maximum number of 
significant digits in the output value. 




The precision field has no effect on these field types. 


s 


The precision field is where you specify the maximum number of 
characters in the output value. Excess characters are not output. 
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Requires 



Example 



The optional characters 1 or l may immediately precede conversion type to 
respectively specify long versions of the integer types d, i, u, o, x, and x. 

You must ensure that the argument type matches that of the format specifica- 
tion. You can use type casts to ensure that the proper type is passed to print- 
out. 



Nothing. 



Print mikroElektronika example's header file to UART 

void PrintHandler (char c){ 

UARTl_Write (c) ; 
} 

void main ( ){ 

UARTl_Init (9600) ; 
Delayjns (100) ; 

Printout (PrintHandler, "/*\r\n" 

* Project name:\r\n' 



of Printout () function) \ r\ n 



2006. \r\n' 



of the Printout () function\r 



PIC18F8520\r\n" 



%10.3fMHz\r\n' 



for PIC\r\n' 



PrintOutExample (Sample usage 

* Copyright :\ r\ n" 

(c) MikroElektronika, 

* Revision History :\ r\ n" 

20060710:\r\n" 

- Initial release\r\n" 

* Description :\ r\ n" 

Simple demonstration on usage 
\n" 

* Test configuration :\ r\ n" 

MCU: 



Dev. Board: 
Oscillator : 

Ext. Modules: 
SW: 



BigPIC5\r\n" 
HS, 

None .\ r\ n" 
mikroC PRO 



* NOTES:\r\n" 

None A r\ n" 
*/\r\n", Get Fosc kHz ( ) /1000 . ) ; 
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SETJMP LIBRARY 

This library contains functions and types definitions for bypassing the normal function call and 
return discipline. The type declared is jmpbuf which is an array type suitable for holding the infor- 
mation needed to restore a calling environment. 

Type declaration is contained in sejmpl 6.h and setjmpl 8.h header files for PIC1 6 and PIC1 8 fam- 
ily mcus respectively. These headers can be found in the include folder of the compiler. The imple- 
mentation of this library is different for PIC16 and PIC18 family mcus. For PIC16 family Setjmp 
and Longjmp are implemented as macros defined in setjmpl 6. h header file and for PIC18 family 
as functions defined in setjmp library file. 

Note: Due to PIC16 family specific of not being able to read/write stack pointer, the program exe- 
cution after Longjmp ivocation occurs depends on the stack content. That is why, for PIC16 fam- 
ily only, implementation of Setjmp and Longjmp functions is not ANSI C standard compliant. 

Library Routines 

- Setjmp 

- Longjmp 



Setjmp 



Prototype 


int setjmp (jmp buf env); 


Returns 


if the return is from direct invocation it returns 

if the return is from a call to the longjmp it returns nonzero value 


Description 


This function saves calling position in jmp buf for later use by longjmp. The 
parameter env: array of type (jmp_buf) suitible for holding the information need- 
ed for restoring calling environment. 


Requires 


Nothing. 


Example 


setjmp (buf) ; 
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Longjmp 



Prototype 


void longjmp (jmp buf env, int val); 


Returns 


longjmp causes setjmp to return val, if val is it will return 1 . 


Description 


Restores calling environment saved in jmp buf by most recent invocation of 
setjmp macro. If there has been no such invocation, or function conatinig the invo- 
cation of setjmp has terminated in the interim, the behaviour is undefined. Param- 
eter env: array of type (jmp_buf) holding the information saved by corresponding 
setjmp invocation, vai: char value, that will return corresponding setjmp. 


Requires 


Invocation of Longjmp must occur before return from the function in which Setjmp 
was called encounters. 


Example 


longjmp (buf, 2); 
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Example demonstrates function cross calling using setjmp and longjmp functions. 
When called, Setjmp() saves its calling environment in its jmp_buf argument for later 
use by the Longjmp(). Longjmp(), on the other hand, restores the environment 
saved by the most recent invocation of the Setjmp() with the corresponding jmp_buf 
argument. The given example is for P16. 
#include <Setjmp16.h> 

#include <Set jmpl6 . h> 

jmp_buf buf; // Note: Program flow diagrams are indexed 

according 

// to the sequence of execution 

void func33(){ // 2< 1 

// I 

// I 

// 3 >| 

// I I 

// I I 

// I I 

// I I 

// 1< | | | 

// III 

// III 

2) // 3< 1 

// 4— >| | | 

// III 

// 2 >| 

// I I 

// 4<— | | 

// 5 | >depends on stack content 

// I 

// I 

// I 

// I 

// 

// I 

// I 

// 

// ! >| 

// 
// 





asm nop 

longjmp 
asm nop 


(buf, 


2) 


} 








void func 


(){ 






portb = 3; 

if (setjmp (buf) 

portb = 1; 
else 

func 3 3 ( ) ; 
asm nop; 


} 








void main 


{ 






PORTB = 
TRISB = 


0; 
0; 






asm nop 








func ( ) ; 








asm nop 
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SPRINT LIBRARY 

The mikroC PRO for PIC provides the standard ANSI C Sprintf function for easy data formatting. 

Note: In addition to ANSI C standard, the Sprint Library also includes two limited versions of the 
sprintf function (sprinti and sprinti). These functions take less ROM and RAM and may be 
more convenient for use in some cases. 

Functions 

- sprintf 

- sprinti 

- sprinti 



sprintf 



Prototype 



sprintf (char *wh, const char *f, ...); 



Returns 



The function returns the number of characters actually written to destination 
string. 



Description 



sprintf is used to format data and print them into destination string. 

Parameters: 

-wh: destination string 
- f : format string 

The f argument is a format string and may be composed of characters, escape 
sequences, and format specifications. Ordinary characters and escape 
sequences are copied to the destination string in the order in which they are inter- 
preted. Format specifications always begin with a percent sign ( ) and require 
additional arguments to be included in the function call. 

The format string is read from left to right. The first format specification encoun- 
tered refers to the first argument after f and then converts and outputs it using 
the format specification. The second format specification accesses the second 
argument after f, and so on. If there are more arguments than format specifica- 
tions, then these extra arguments are ignored. Results are unpredictable if there 
are not enough arguments for the format specifications. The format specifications 
have the following format: 

% [ flags] [ width] [ .precision] [ { 1 | L } ] conversion_type 
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Each field in the format specification can be a single character or a number which 
specifies a particular format option. The conversiontype field is where a single 
character specifies that the argument is interpreted as a character, string, num- 
ber, or pointer, as shown in the following table: 



conversion type 


Argument Type 


Output Format 


d 


int 


Signed decimal number 


u 


unsigned int 


Unsigned decimal number 





unsigned int 


Unsigned octal number 


X 


unsigned int 


Unsigned hexadecimal number using 
0123456789abcdef 


X 


unsigned int 


Unsigned hexadecimal number using 
0123456789ABCEDF 


f 


double 


Floating-point number using the format [- 
Idddd.dddd 


e 


double 


Floating-point number using the format [- 
|d.dddde[-]dd 


E 


double 


Floating-point number using the format [- 
|d.ddddE[-]dd 


g 


double 


Floating-point number using either e orf 
format, whichever is more compact for the 
specified value and precision 


c 


int 


int is Converted to an unsigned char, 

and the resulting character is written 


s 


char * 


String with a terminating null character 


p 


void * 


Pointer value, the X format is used 


% 


<none> 


A % is written. No argument is converted. 
The complete conversion specification 
shall be %%. 
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The flags field is where a single character is used to justify the output and to 
print +/- signs and blanks, decimal points, and octal and hexadecimal prefixes, 
as shown in the following table. 



flags 


Meaning 


+ 


Left justify the output in the specified field width. 




Prefix the output value with + or - sign if the output is a signed type. 


space 
(' ') 


Prefix the output value with a blank if it is a signed positive value. 
Otherwise, no blank is prefixed. 


# 


Prefix a non-zero output value with o )x, or ox when used with o 
and x field types, respectively. When used with the e, e, f, g, and g 
field types, the 8 flag forces the output value to include a decimal 
point. In any other case the | flag is ignored. 


* 


Ignore format specifier. 



The width field is a non-negative number that specifies a minimum number of 
printed characters. If a number of characters in the output value is less than width, 
blanks are added on the left or right (when the - flag is specified) in order to pad 
to the minimum width. If the width is prefixed with 0, then zeros are padded 
instead of blanks. The width field never truncates a field. If the length of the out- 
put value exceeds the specified width, all characters are output. 

The precision field is a non-negative number that specifies the number of char- 
acters to print, number of significant digits, or number of decimal places. The pre- 
cision field can cause truncation or rounding of the output value in the case of a 
floating-point number as specified in the following table. 



flags 


MeaningMeaning of the precision field 


d, u, o, 
x, X 


The precision field is where you specify the minimum number of 
digits that will be included in the output value. Digits are not trun- 
cated if the number of digits in an argument exceeds that defined 
in the precision field. If the number of digits in the argument is 
less than the precision field, the output value is padded on the 
left with zeros. 


f 


The precision field is where you specify the number of digits to 
the right of the decimal point. The last digit is rounded. 


e, E 


The precision field is where you specify the number of digits to 
the right of the decimal point. The last digit is rounded. 


g 


The precision field is where you specify the maximum number of 
significant digits in the output value. 




The precision field has no effect on these field types. 


s 


The precision field is where you specify the maximum number of 
characters in the output value. Excess characters are not output. 
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Description 



The optional characters 1 or l may immediately precede conversion type to 
respectively specify long versions of the integer types d, i, u, o, x, and x. 

You must ensure that the argument type matches that of the format specification. 
You can use type casts to ensure that the proper type is passed to sprintf . 



sprintl 



Prototype 



Returns 



Description 



sprintl (char *wh, const char *f,... 



The function returns the number of characters actually written to destination 
string. 



The same as sprintf, except it doesn't support float-type numbers. 



sprinti 



Prototype 



sprinti (char *wh, const char *f, . 



Returns 



The function returns the number of characters actually written to destination 
string. 



Description 



The same as sprintf, except it doesn't support long integers and float-type num- 
bers. 
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Library Example 

This is a demonstration of the standard C library sprintf routine usage. Three differ- 
ent representations of the same floating poing number obtained by using the sprintf 
routine are sent via UART 

double ww = -1 . 2587538e + l; 
char buffer[ 15] ; 

// Function for sending string to UART 
void UartWriteText (char *txt) { 
while (* txt) 

UARTl_Write (*txt++) ; 
} 

// Function for sending const string to UART 
void UartWriteConstText (const char *txt) { 
while (* txt) 

UARTl_Write (*txt++) ; 
} 

void main ( ) { 



UARTl_Init (4800) 
Delayjns (10) ; 



// Initialize UART module at 4800 bps 



UartWriteConstText ( "Floating point number representation"); // 
Write message on UART 

sprintf (buff er, "%12e", ww) ; // Format ww and store it to buffer 
UartWriteConstText ( "\ r\ ne format:"); // Write message on UART 
UartWriteText (buffer) ; // Write buffer on UART 

sprintf (buff er, "%12f", ww) ; // Format ww and store it to buffer 
UartWriteConstText ("\r\nf format:"); // Write message on UART 
UartWriteText (buffer) ; // Write buffer on UART 

sprintf (buffer, "%12g", ww) ; // Format ww and store it to buffer 
UartWriteConstText ( "\ r\ ng format:"); // Write message on UART 
UartWriteText (buffer) ; // Write buffer on UART 
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The Time Library contains functions and type definitions for time calculations in the 
UNIX time format which counts the number of seconds since the "epoch". This is 
very convenient for programs that work with time intervals: the difference between 
two UNIX time values is a real-time difference measured in seconds. 

What is the epoch? 

Originally it was defined as the beginning of 1 970 GMT. ( January 1 , 1 970 Julian day 

) GMT, Greenwich Mean Time, is a traditional term for the time zone in England. 

The TimeStruct type is a structure type suitable for time and date storage. Type 
declaration is contained in timelib.h which can be found in the mikroC PRO for PIC 
Time Library Demo example folder. 

Library Routines 

- Time_dateToEpoch 

- Time_epochToDate 

- Time dateDiff 
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Time_dateToEpoch 



Prototype 


long Time dateToEpoch (TimeStruct *ts); 


Returns 


Number of seconds since January 1 , 1 970 OhOOmnOOs. 


Description 


This function returns the unix time : number of seconds since January 1 , 1 970 
OhOOmnOOs. 

Parameters: 

- ts: time and date value for calculating unix time. 


Requires 


Nothing. 


Example 


#include "timelib.h" 

TimeStruct tsl; 

long epoch; 

/* 

* what is the epoch of the date in ts ? 

*/ 
epoch = Time dateToEpoch ( stsl ) ; 



Time_epochToDate 



Prototype 


void Time epochToDate (long e, TimeStruct *ts); 


Returns 


Nothing. 




Converts the unix time to time and date. 




Description 


Parameters: 

- e : unix time (seconds since unix epoch) 






- ts : time and date structure for storing conversion ou 


tput 


Requires 


Nothing. 




#include "timelib.h" 






TimeStruct ts2; 






long epoch; 




Example 


/* 

* what date is epoch 1234567890 ? 

*/ 
epoch = 1234567890; 










Time epochToDate (epoch, &ts2); 
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Prototype 


long Time dateDiff (TimeStruct *tl, TimeStruct *t2); 


Returns 


Time difference in seconds as a signed long. 


Description 


This function compares two dates and returns time difference in seconds as a 
signed long. Result is positive if ti is before t2, result is null if ti is the same as 
t2 and result is negative if ti is after t2. 

Parameters: 

- ti: time and date structure (the first comparison parameter) 
- 12 : time and date structure (the second comparison parameter) 

Note: This function is implemented as macro in the timelib.h header file which 
can be found in the mikroC PRO for PIC Time Library Demo example folder. 


Requires 


Nothing. 


Example 


#include "timelib.h" 

TimeStruct tsl, ts2; 
long diff; 

/* 

* how many seconds between these two dates contained in tsl and 
ts2 buffers? 

*/ 

diff = Time dateDiff (&tsl, &ts2); 
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Library Example 

This example demonstrates Time Library usage. 



#include 



'timelib . h" 



TimeStruct tsl, ts2; 
long epoch; 
long cliff; 

void main ( ) { 

t s 1 . s s = ; 

tsl. mn = 7 ; 

tsl.hh = 17; 

tsl. md = 23; 

tsl. mo = 5 ; 

tsl.yy = 2006; 

/* 

* What is the epoch of the date in ts 

*/ 
epoch = Time_dateToEpoch ( stsl ) ; 



* What date is epoch 1234567890 ? 
*/ 

epoch = 1234567890; 
Time_epochToDate (epoch, sts2); 

/* 

* How much seconds between this two dates ? 
*/ 

diff = Time dateDif f (stsl, Sts2); 
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TRIGONOMETRY LIBRARY 

The mikroC PRO for PIC implements fundamental trigonometry functions. These functions are 
implemented as look-up tables. Trigonometry functions are implemented in integer format in order 
to save memory. 



Library Routines 

- sinE3 

- cosE3 

sinE3 



Prototype 


int sinE3 (unsigned angle cleg) ; 


Returns 


The function returns the sine of input parameter. 


Description 


The function calculates sine multiplied by 1000 and rounded to the nearest integer: 

result := round (sin (angle deg)*1000) 

Parameters: 

-angle deg : input angle in degrees 

Note: Return value range: -1000. .1000. 


Requires 


Nothing. 


Example 


int res; 

res = sinE3(45); // result is 707 



MIKROELEKTRONIKA - SOFTWARE AND HARDWARE SOLUTIONS FOR EMBEDDED WORLD 605 



CHAPTER 7 

Libraries 



mikroC PRO for PIC 



cosE3 



Prototype 


int cosE3 (unsigned angle deg) ; 


Returns 


The function returns the cosine of input parameter. 




The function calculates cosine multiplied by 1000 and rounded to the nearest 




integer: 




result := round (cos (angle deg)*1000) 


Description 


Parameters: 




-angle deg: input angle in degrees 




Note: Return value range: -1000. .1000. 


Requires 


Nothing. 




int res; 


Example 






res = cosE3(196); // result is -193 
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